1 files changed, 40 insertions, 7 deletions
diff --git a/docs/html/training/articles/keystore.jd b/docs/html/training/articles/keystore.jd
index bbbda67..fea3b2c 100644
--- a/docs/html/training/articles/keystore.jd
+++ b/docs/html/training/articles/keystore.jd
@@ -26,11 +26,12 @@ page.title=Android Keystore System
   </div>
 </div>
 
-<p>The Android Keystore system lets you store private keys
-  in a container to make it more difficult to extract from the
-  device. Once keys are in the keystore, they can be used for
-  cryptographic operations with the private key material remaining
-  non-exportable.</p>
+<p>The Android Keystore system lets you store cryptographic keys in a container
+  to make it more difficult to extract from the device. Once keys are in the
+  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.</p>
 
 <p>The Keystore system is used by the {@link
   android.security.KeyChain} API as well as the Android
@@ -59,7 +60,8 @@ Android Keystore Provider</h2>
 
 <p>
 To use this feature, you use the standard {@link java.security.KeyStore}
-and {@link java.security.KeyPairGenerator} classes along with the
+and {@link java.security.KeyPairGenerator} or
+{@link javax.crypto.KeyGenerator} classes along with the
 {@code AndroidKeyStore} provider introduced in Android 4.3 (API level 18).</p>
 
 <p>{@code AndroidKeyStore} is registered as a {@link
@@ -67,7 +69,9 @@ and {@link java.security.KeyPairGenerator} classes along with the
   java.security.KeyStore#getInstance(String) KeyStore.getInstance(type)}
   method and as a provider for use with the {@link
   java.security.KeyPairGenerator#getInstance(String, String)
-  KeyPairGenerator.getInstance(algorithm, provider)} method.</p>
+  KeyPairGenerator.getInstance(algorithm, provider)} and {@link
+  javax.crypto.KeyGenerator#getInstance(String, String)
+  KeyGenerator.getInstance(algorithm, provider)} methods.</p>
 
 <h3 id="GeneratingANewPrivateKey">Generating a New Private Key</h3>
 
@@ -81,6 +85,11 @@ and {@link java.security.KeyPairGenerator} classes along with the
 
 {@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java generate}
 
+<h3 id="GeneratingANewSecretKey">Generating a New Secret Key</h3>
+
+<p>To generate the key, use a {@link javax.crypto.KeyGenerator} with
+  {@link android.security.KeyGeneratorSpec}.
+
 <h3 id="WorkingWithKeyStoreEntries">Working with Keystore Entries</h3>
 
 <p>Using the {@code AndroidKeyStore} provider takes place through
@@ -105,3 +114,27 @@ and {@link java.security.KeyPairGenerator} classes along with the
 <p>Similarly, verify data with the {@link java.security.Signature#verify(byte[])} method:</p>
 
 {@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java verify}
+
+<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.
+
+<p>When a key is configured to require user authentication, it is also 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()}).
+  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, AuthenticationCallback, int) 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>