1 files changed, 36 insertions, 23 deletions
diff --git a/docs/html/training/articles/keystore.jd b/docs/html/training/articles/keystore.jd
index fca958e..52cb13e 100644
--- a/docs/html/training/articles/keystore.jd
+++ b/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
-secure lock screen credentials. This is a security measure which makes it possible to generate
-cryptographic assertions about the user having been authenticated.
+is only authorized to be used if the user has been authenticated. The user is authenticated using a
+subset of their secure lock screen credentials (pattern/PIN/password, fingerprint).
 
-<p>When a key is configured to require user authentication, it is also configured to operate in one
-of the two modes:
+<p>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 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
-  for use as soon as the user unlocks the secure lock screen or confirms their secure lock screen
-  credentials using the {@link android.app.KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence) KeyguardManager.createConfirmDeviceCredentialIntent}
-  flow. Each key specifies for how long the authorization remains valid for that key. Such keys
-  can only be generated or imported if the secure lock screen is enabled (see {@link android.app.KeyguardManager#isDeviceSecure() KeyguardManager.isDeviceSecure()}).
-  These keys become permanently invalidated once the secure lock screen is disabled or forcibly
-  reset (e.g. by a Device Admin).</li>
-<li>User authentication is required for every use of the key. In this mode, a specific operation
-  involving a specific key is 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 all fingerprints are unenrolled.</li>
-</ul>
+<li>User authentication authorizes the use of keys for a duration of time. All keys in this mode are
+  authorized for use as soon as the user unlocks the secure lock screen or confirms their secure
+  lock screen credential using the
+  {@link android.app.KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence) KeyguardManager.createConfirmDeviceCredentialIntent}
+  flow. The duration for which the authorization remains valid is specific to each key, as specified
+  using {@code setUserAuthenticationValidityDurationSeconds} during key generation or import. Such
+  keys can only be generated or imported if the secure lock screen is enabled (see
+  {@link android.app.KeyguardManager#isDeviceSecure() KeyguardManager.isDeviceSecure()}). These keys
+  become permanently invalidated once the secure lock screen is disabled (reconfigured to None,
+  Swipe or other mode which does not authenticate the user) or forcibly reset (e.g. by a Device
+  Administrator).</li>
+<li>User authentication authorizes a specific cryptographic operation associated with one key. In
+  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>
+\ No newline at end of file