Merge "Improve documentation for keys requiring user auth." into mnc-dev

docs/html/training/articles/keystore.jd

@@ -32,7 +32,7 @@ page.title=Android Keystore System
   keystore, they can be used for cryptographic operations with the key material
   remaining non-exportable. Moreover, it offers facilities to restrict when and
   how keys can be used, such as requiring user authentication for key use or
-  restricting encryption keys to be used only in certain block modes. See
+  restricting keys to be used only in certain cryptographic modes. See
   <a href="#SecurityFeatures">Security Features</a> section for more information.</p>
 
 <p>The Keystore system is used by the {@link
@@ -48,7 +48,8 @@ Android Keystore system protects key material from unauthorized use. Firstly, An
 mitigates unauthorized use of key material outside of the Android device by preventing extraction of
 the key material from application processes and from the Android device as a whole. Secondly,
 Android KeyStore mitigates unauthorized use of key material on the Android device by making apps
-specify authorized uses of their keys and then enforcing these restrictions.
+specify authorized uses of their keys and then enforcing these restrictions outside of the apps'
+processes.
 
 <h3 id="ExtractionPrevention">Extraction Prevention</h3>
 
@@ -78,14 +79,16 @@ Key material of Android Keystore keys is protected from extraction using two sec
 To mitigate unauthorized use of keys on the Android device, Android Keystore lets apps specify
 authorized uses of their keys when generating or importing the keys. Once a key is generated or
 imported, its authorizations can not be changed. Authorizations are then enforced by the Android
-Keystore whenever the key is used.
+Keystore whenever the key is used. This is an advanced security feature which is generally useful
+only if your requirements are that a compromise of your application process after key
+generation/import (but not before or during) cannot lead to unauthorized uses of the key.
 
 <p>Supported key use authorizations fall into the following categories:
 <ul>
 <li><em>cryptography</em>: authorized key algorithm, operations or purposes (encrypt, decrypt, sign,
-  verify), padding schemes, block modes, digests with which the key can be used</li>
+  verify), padding schemes, block modes, digests with which the key can be used;</li>
 <li><em>temporal validity interval</em>: interval of time during which the key is authorized for
-  use</li>
+  use;</li>
 <li><em>user authentication</em>: the key can only be used if the user has been authenticated
   recently enough. See <a href="#UserAuthentication">Requiring User Authentication For Key Use</a>.
   </li>
@@ -181,23 +184,33 @@ and {@link java.security.KeyPairGenerator} or
 <h3 id="UserAuthentication">Requiring User Authentication For Key Use</h3>
 
 <p>When generating or importing a key into the {@code AndroidKeyStore} you can specify that the key
-can only be used if user has been authenticated. The user is authenticated using a subset of their
+is only authorized to be used if the user has been authenticated. The user is authenticated using a
-secure lock screen credentials. This is a security measure which makes it possible to generate
+subset of their secure lock screen credentials (pattern/PIN/password, fingerprint).
-cryptographic assertions about the user having been authenticated.
 
-<p>When a key is configured to require user authentication, it is also configured to operate in one
+<p>This is an advanced security feature which is generally useful only if your requirements are that
-of the two modes:
+a compromise of your application process after key generation/import (but not before or during)
+cannot bypass the requirement for the user to be authenticated to use the key.
+
+<p>When a key is authorized to be used only if the user has been authenticated, it is configured to
+operate in one of the two modes:
 <ul>
-<li>User authentication is valid for a duration of time. All keys in this mode are authorized
+<li>User authentication authorizes the use of keys for a duration of time. All keys in this mode are
-  for use as soon as the user unlocks the secure lock screen or confirms their secure lock screen
+  authorized for use as soon as the user unlocks the secure lock screen or confirms their secure
-  credentials using the {@link android.app.KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence) KeyguardManager.createConfirmDeviceCredentialIntent}
+  lock screen credential using the
-  flow. Each key specifies for how long the authorization remains valid for that key. Such keys
+  {@link android.app.KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence) KeyguardManager.createConfirmDeviceCredentialIntent}
-  can only be generated or imported if the secure lock screen is enabled (see {@link android.app.KeyguardManager#isDeviceSecure() KeyguardManager.isDeviceSecure()}).
+  flow. The duration for which the authorization remains valid is specific to each key, as specified
-  These keys become permanently invalidated once the secure lock screen is disabled or forcibly
+  using {@code setUserAuthenticationValidityDurationSeconds} during key generation or import. Such
-  reset (e.g. by a Device Admin).</li>
+  keys can only be generated or imported if the secure lock screen is enabled (see
-<li>User authentication is required for every use of the key. In this mode, a specific operation
+  {@link android.app.KeyguardManager#isDeviceSecure() KeyguardManager.isDeviceSecure()}). These keys
-  involving a specific key is authorized by the user. Currently, the only means of such
+  become permanently invalidated once the secure lock screen is disabled (reconfigured to None,
-  authorization is fingerprint authentication: {@link android.hardware.fingerprint.FingerprintManager#authenticate(CryptoObject, CancellationSignal, int, AuthenticationCallback, Handler) FingerprintManager.authenticate}.
+  Swipe or other mode which does not authenticate the user) or forcibly reset (e.g. by a Device
-  Such keys can only be generated or imported if at least one fingerprint is enrolled (see {@link android.hardware.fingerprint.FingerprintManager#hasEnrolledFingerprints() FingerprintManager.hasEnrolledFingerprints}).
+  Administrator).</li>
-  These keys become permanently invalidated once all fingerprints are unenrolled.</li>
+<li>User authentication authorizes a specific cryptographic operation associated with one key. In
-</ul>
+  this mode, each operation involving such a key must be individually authorized by the user.
+  Currently, the only means of such authorization is fingerprint authentication:
+  {@link android.hardware.fingerprint.FingerprintManager#authenticate(CryptoObject, CancellationSignal, int, AuthenticationCallback, Handler) FingerprintManager.authenticate}.
+  Such keys can only be generated or imported if at least one fingerprint is enrolled (see
+  {@link android.hardware.fingerprint.FingerprintManager#hasEnrolledFingerprints() FingerprintManager.hasEnrolledFingerprints}).
+  These keys become permanently invalidated once a new fingerprint is enrolled or all fingerprints
+  are unenrolled.</li>
+</ul>

keystore/java/android/security/keystore/KeyGenParameterSpec.java

@@ -19,16 +19,20 @@ package android.security.keystore;
 import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.app.KeyguardManager;
+import android.hardware.fingerprint.FingerprintManager;
 import android.text.TextUtils;
 
 import java.math.BigInteger;
 import java.security.KeyPairGenerator;
+import java.security.Signature;
 import java.security.cert.Certificate;
 import java.security.spec.AlgorithmParameterSpec;
 import java.util.Date;
 
 import javax.crypto.Cipher;
 import javax.crypto.KeyGenerator;
+import javax.crypto.Mac;
 import javax.security.auth.x500.X500Principal;
 
 /**
@@ -62,10 +66,15 @@ import javax.security.auth.x500.X500Principal;
  * <p>NOTE: If a private key is not authorized to sign the self-signed certificate, then the
  * certificate will be created with an invalid signature which will not verify. Such a certificate
  * is still useful because it provides access to the public key. To generate a valid
- * signature for the certificate the key needs to be authorized for
+ * signature for the certificate the key needs to be authorized for all of the following:
- * {@link KeyProperties#PURPOSE_SIGN}, a suitable digest or {@link KeyProperties#DIGEST_NONE}, and
+ * <ul>
- * {@link KeyProperties#SIGNATURE_PADDING_RSA_PKCS1} or
+ * <li>{@link KeyProperties#PURPOSE_SIGN},</li>
- * {@link KeyProperties#ENCRYPTION_PADDING_NONE}.
+ * <li>operation without requiring the user to be authenticated (see
+ * {@link Builder#setUserAuthenticationRequired(boolean)}),</li>
+ * <li>suitable digest or {@link KeyProperties#DIGEST_NONE},</li>
+ * <li>(RSA keys only) padding scheme {@link KeyProperties#SIGNATURE_PADDING_RSA_PKCS1} or
+ * {@link KeyProperties#ENCRYPTION_PADDING_NONE}.</li>
+ * </ul>
  *
  * <p>NOTE: The key material of the generated symmetric and private keys is not accessible. The key
  * material of the public keys is accessible.
@@ -393,28 +402,32 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
     }
 
     /**
-     * Returns {@code true} if user authentication is required for this key to be used.
+     * Returns {@code true} if the key is authorized to be used only if the user has been
+     * authenticated.
      *
-     * <p>This restriction applies only to private key operations. Public key operations are not
+     * <p>This authorization applies only to secret key and private key operations. Public key
-     * restricted.
+     * operations are not restricted.
      *
      * @see #getUserAuthenticationValidityDurationSeconds()
+     * @see Builder#setUserAuthenticationRequired(boolean)
      */
     public boolean isUserAuthenticationRequired() {
         return mUserAuthenticationRequired;
     }
 
     /**
-     * Gets the duration of time (seconds) for which this key can be used after the user is
+     * Gets the duration of time (seconds) for which this key is authorized to be used after the
-     * successfully authenticated. This has effect only if user authentication is required.
+     * user is successfully authenticated. This has effect only if user authentication is required
+     * (see {@link #isUserAuthenticationRequired()}).
      *
-     * <p>This restriction applies only to private key operations. Public key operations are not
+     * <p>This authorization applies only to secret key and private key operations. Public key
-     * restricted.
+     * operations are not restricted.
      *
      * @return duration in seconds or {@code -1} if authentication is required for every use of the
-     * key.
+     *         key.
      *
      * @see #isUserAuthenticationRequired()
+     * @see Builder#setUserAuthenticationValidityDurationSeconds(int)
      */
     public int getUserAuthenticationValidityDurationSeconds() {
         return mUserAuthenticationValidityDurationSeconds;
@@ -738,22 +751,38 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
         }
 
         /**
-         * Sets whether user authentication is required to use this key.
+         * Sets whether this key is authorized to be used only if the user has been authenticated.
          *
-         * <p>By default, the key can be used without user authentication.
+         * <p>By default, the key is authorized to be used regardless of whether the user has been
+         * authenticated.
          *
-         * <p>When user authentication is required, the user authorizes the use of the key by
+         * <p>When user authentication is required:
-         * authenticating to this Android device using a subset of their secure lock screen
+         * <ul>
-         * credentials. Different authentication methods are used depending on whether the every
+         * <li>The key can only be generated if secure lock screen is set up (see
-         * use of the key must be authenticated (as specified by
+         * {@link KeyguardManager#isDeviceSecure()}). Additionally, if the key requires that user
-         * {@link #setUserAuthenticationValidityDurationSeconds(int)}).
+         * authentication takes place for every use of the key (see
+         * {@link #setUserAuthenticationValidityDurationSeconds(int)}), at least one fingerprint
+         * must be enrolled (see {@link FingerprintManager#hasEnrolledFingerprints()}).</li>
+         * <li>The use of the key must be authorized by the user by authenticating to this Android
+         * device using a subset of their secure lock screen credentials such as
+         * password/PIN/pattern or fingerprint.
          * <a href="{@docRoot}training/articles/keystore.html#UserAuthentication">More
          * information</a>.
+         * <li>The key will become <em>irreversibly invalidated</em> once the secure lock screen is
+         * disabled (reconfigured to None, Swipe or other mode which does not authenticate the user)
+         * or when the secure lock screen is forcibly reset (e.g., by a Device Administrator).
+         * Additionally, if the key requires that user authentication takes place for every use of
+         * the key, it is also irreversibly invalidated once a new fingerprint is enrolled or once\
+         * no more fingerprints are enrolled. Attempts to initialize cryptographic operations using
+         * such keys will throw {@link KeyPermanentlyInvalidatedException}.</li>
+         * </ul>
          *
-         * <p>This restriction applies only to private key operations. Public key operations are not
+         * <p>This authorization applies only to secret key and private key operations. Public key
-         * restricted.
+         * operations are not restricted.
          *
          * @see #setUserAuthenticationValidityDurationSeconds(int)
+         * @see KeyguardManager#isDeviceSecure()
+         * @see FingerprintManager#hasEnrolledFingerprints()
          */
         @NonNull
         public Builder setUserAuthenticationRequired(boolean required) {
@@ -762,15 +791,39 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
         }
 
         /**
-         * Sets the duration of time (seconds) for which this key can be used after the user is
+         * Sets the duration of time (seconds) for which this key is authorized to be used after the
-         * successfully authenticated. This has effect only if user authentication is required.
+         * user is successfully authenticated. This has effect if the key requires user
+         * authentication for its use (see {@link #setUserAuthenticationRequired(boolean)}).
          *
-         * <p>By default, the user needs to authenticate for every use of the key.
+         * <p>By default, if user authentication is required, it must take place for every use of
+         * the key.
          *
-         * @param seconds duration in seconds or {@code -1} if the user needs to authenticate for
+         * <p>Cryptographic operations involving keys which require user authentication to take
-         *        every use of the key.
+         * place for every operation can only use fingerprint authentication. This is achieved by
+         * initializing a cryptographic operation ({@link Signature}, {@link Cipher}, {@link Mac})
+         * with the key, wrapping it into a {@link FingerprintManager.CryptoObject}, invoking
+         * {@code FingerprintManager.authenticate} with {@code CryptoObject}, and proceeding with
+         * the cryptographic operation only if the authentication flow succeeds.
+         *
+         * <p>Cryptographic operations involving keys which are authorized to be used for a duration
+         * of time after a successful user authentication event can only use secure lock screen
+         * authentication. These cryptographic operations will throw
+         * {@link UserNotAuthenticatedException} during initialization if the user needs to be
+         * authenticated to proceed. This situation can be resolved by the user unlocking the secure
+         * lock screen of the Android or by going through the confirm credential flow initiated by
+         * {@link KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence)}.
+         * Once resolved, initializing a new cryptographic operation using this key (or any other
+         * key which is authorized to be used for a fixed duration of time after user
+         * authentication) should succeed provided the user authentication flow completed
+         * successfully.
+         *
+         * @param seconds duration in seconds or {@code -1} if user authentication must take place
+         *        for every use of the key.
          *
          * @see #setUserAuthenticationRequired(boolean)
+         * @see FingerprintManager
+         * @see FingerprintManager.CryptoObject
+         * @see KeyguardManager
          */
         @NonNull
         public Builder setUserAuthenticationValidityDurationSeconds(

keystore/java/android/security/keystore/KeyInfo.java

@@ -238,17 +238,27 @@ public class KeyInfo implements KeySpec {
     }
 
     /**
-     * Returns {@code true} if user authentication is required for this key to be used.
+     * Returns {@code true} if the key is authorized to be used only if the user has been
+     * authenticated.
+     *
+     * <p>This authorization applies only to secret key and private key operations. Public key
+     * operations are not restricted.
      *
      * @see #getUserAuthenticationValidityDurationSeconds()
+     * @see KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean)
+     * @see KeyProtection.Builder#setUserAuthenticationRequired(boolean)
      */
     public boolean isUserAuthenticationRequired() {
         return mUserAuthenticationRequired;
     }
 
     /**
-     * Gets the duration of time (seconds) for which this key can be used after the user is
+     * Gets the duration of time (seconds) for which this key is authorized to be used after the
-     * successfully authenticated. This has effect only if user authentication is required.
+     * user is successfully authenticated. This has effect only if user authentication is required
+     * (see {@link #isUserAuthenticationRequired()}).
+     *
+     * <p>This authorization applies only to secret key and private key operations. Public key
+     * operations are not restricted.
      *
      * @return duration in seconds or {@code -1} if authentication is required for every use of the
      *         key.

keystore/java/android/security/keystore/KeyPermanentlyInvalidatedException.java

@@ -21,12 +21,13 @@ import java.security.InvalidKeyException;
 /**
  * Indicates that the key can no longer be used because it has been permanently invalidated.
  *
- * <p>This can currently occur only for keys that require user authentication. Such keys are
+ * <p>This only occurs for keys which are authorized to be used only if the user has been
- * permanently invalidated once the secure lock screen is disabled (i.e., reconfigured to None,
+ * authenticated. Such keys are permanently and irreversibly invalidated once the secure lock screen
- * Swipe or other mode which does not authenticate the user) or when the secure lock screen is
+ * is disabled (i.e., reconfigured to None, Swipe or other mode which does not authenticate the
- * forcibly reset (e.g., by Device Admin). Additionally, keys configured to require user
+ * user) or when the secure lock screen is forcibly reset (e.g., by Device Admin). Additionally,
- * authentication for every use of the key are also permanently invalidated once a new fingerprint
+ * keys configured to require user authentication to take place for every of the keys, are also
- * is enrolled or once no more fingerprints are enrolled.
+ * permanently invalidated once a new fingerprint is enrolled or once no more fingerprints are
+ * enrolled.
  */
 public class KeyPermanentlyInvalidatedException extends InvalidKeyException {
 

keystore/java/android/security/keystore/KeyProtection.java

@@ -19,13 +19,17 @@ package android.security.keystore;
 import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.app.KeyguardManager;
+import android.hardware.fingerprint.FingerprintManager;
 
 import java.security.Key;
+import java.security.Signature;
 import java.security.KeyStore.ProtectionParameter;
 import java.security.cert.Certificate;
 import java.util.Date;
 
 import javax.crypto.Cipher;
+import javax.crypto.Mac;
 
 /**
  * Specification of how a key or key pair is secured when imported into the
@@ -257,22 +261,32 @@ public final class KeyProtection implements ProtectionParameter {
     }
 
     /**
-     * Returns {@code true} if user authentication is required for this key to be used.
+     * Returns {@code true} if the key is authorized to be used only if the user has been
+     * authenticated.
+     *
+     * <p>This authorization applies only to secret key and private key operations. Public key
+     * operations are not restricted.
      *
      * @see #getUserAuthenticationValidityDurationSeconds()
+     * @see Builder#setUserAuthenticationRequired(boolean)
      */
     public boolean isUserAuthenticationRequired() {
         return mUserAuthenticationRequired;
     }
 
     /**
-     * Gets the duration of time (seconds) for which this key can be used after the user is
+     * Gets the duration of time (seconds) for which this key is authorized to be used after the
-     * successfully authenticated. This has effect only if user authentication is required.
+     * user is successfully authenticated. This has effect only if user authentication is required
+     * (see {@link #isUserAuthenticationRequired()}).
+     *
+     * <p>This authorization applies only to secret key and private key operations. Public key
+     * operations are not restricted.
      *
      * @return duration in seconds or {@code -1} if authentication is required for every use of the
      *         key.
      *
      * @see #isUserAuthenticationRequired()
+     * @see Builder#setUserAuthenticationValidityDurationSeconds(int)
      */
     public int getUserAuthenticationValidityDurationSeconds() {
         return mUserAuthenticationValidityDurationSeconds;
@@ -479,19 +493,38 @@ public final class KeyProtection implements ProtectionParameter {
         }
 
         /**
-         * Sets whether user authentication is required to use this key.
+         * Sets whether this key is authorized to be used only if the user has been authenticated.
          *
-         * <p>By default, the key can be used without user authentication.
+         * <p>By default, the key is authorized to be used regardless of whether the user has been
+         * authenticated.
          *
-         * <p>When user authentication is required, the user authorizes the use of the key by
+         * <p>When user authentication is required:
-         * authenticating to this Android device using a subset of their secure lock screen
+         * <ul>
-         * credentials. Different authentication methods are used depending on whether the every
+         * <li>The key can only be import if secure lock screen is set up (see
-         * use of the key must be authenticated (as specified by
+         * {@link KeyguardManager#isDeviceSecure()}). Additionally, if the key requires that user
-         * {@link #setUserAuthenticationValidityDurationSeconds(int)}).
+         * authentication takes place for every use of the key (see
+         * {@link #setUserAuthenticationValidityDurationSeconds(int)}), at least one fingerprint
+         * must be enrolled (see {@link FingerprintManager#hasEnrolledFingerprints()}).</li>
+         * <li>The use of the key must be authorized by the user by authenticating to this Android
+         * device using a subset of their secure lock screen credentials such as
+         * password/PIN/pattern or fingerprint.
          * <a href="{@docRoot}training/articles/keystore.html#UserAuthentication">More
          * information</a>.
+         * <li>The key will become <em>irreversibly invalidated</em> once the secure lock screen is
+         * disabled (reconfigured to None, Swipe or other mode which does not authenticate the user)
+         * or when the secure lock screen is forcibly reset (e.g., by a Device Administrator).
+         * Additionally, if the key requires that user authentication takes place for every use of
+         * the key, it is also irreversibly invalidated once a new fingerprint is enrolled or once\
+         * no more fingerprints are enrolled. Attempts to initialize cryptographic operations using
+         * such keys will throw {@link KeyPermanentlyInvalidatedException}.</li>
+         * </ul>
+         *
+         * <p>This authorization applies only to secret key and private key operations. Public key
+         * operations are not restricted.
          *
          * @see #setUserAuthenticationValidityDurationSeconds(int)
+         * @see KeyguardManager#isDeviceSecure()
+         * @see FingerprintManager#hasEnrolledFingerprints()
          */
         @NonNull
         public Builder setUserAuthenticationRequired(boolean required) {
@@ -500,15 +533,39 @@ public final class KeyProtection implements ProtectionParameter {
         }
 
         /**
-         * Sets the duration of time (seconds) for which this key can be used after the user is
+         * Sets the duration of time (seconds) for which this key is authorized to be used after the
-         * successfully authenticated. This has effect only if user authentication is required.
+         * user is successfully authenticated. This has effect if the key requires user
+         * authentication for its use (see {@link #setUserAuthenticationRequired(boolean)}).
          *
-         * <p>By default, the user needs to authenticate for every use of the key.
+         * <p>By default, if user authentication is required, it must take place for every use of
+         * the key.
          *
-         * @param seconds duration in seconds or {@code -1} if the user needs to authenticate for
+         * <p>Cryptographic operations involving keys which require user authentication to take
-         *        every use of the key.
+         * place for every operation can only use fingerprint authentication. This is achieved by
+         * initializing a cryptographic operation ({@link Signature}, {@link Cipher}, {@link Mac})
+         * with the key, wrapping it into a {@link FingerprintManager.CryptoObject}, invoking
+         * {@code FingerprintManager.authenticate} with {@code CryptoObject}, and proceeding with
+         * the cryptographic operation only if the authentication flow succeeds.
+         *
+         * <p>Cryptographic operations involving keys which are authorized to be used for a duration
+         * of time after a successful user authentication event can only use secure lock screen
+         * authentication. These cryptographic operations will throw
+         * {@link UserNotAuthenticatedException} during initialization if the user needs to be
+         * authenticated to proceed. This situation can be resolved by the user unlocking the secure
+         * lock screen of the Android or by going through the confirm credential flow initiated by
+         * {@link KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence)}.
+         * Once resolved, initializing a new cryptographic operation using this key (or any other
+         * key which is authorized to be used for a fixed duration of time after user
+         * authentication) should succeed provided the user authentication flow completed
+         * successfully.
+         *
+         * @param seconds duration in seconds or {@code -1} if user authentication must take place
+         *        for every use of the key.
          *
          * @see #setUserAuthenticationRequired(boolean)
+         * @see FingerprintManager
+         * @see FingerprintManager.CryptoObject
+         * @see KeyguardManager
          */
         @NonNull
         public Builder setUserAuthenticationValidityDurationSeconds(