Add documentation for AndroidKeyStore

Add exposition about the use cases for AndroidKeyStore and links to the
API sample application for different use cases.

Bug: 8608817
Change-Id: Ic4ce9405781c92f12687895b28c671661ea5524f

1 files changed, 107 insertions, 0 deletions

diff --git a/docs/html/training/articles/keystore.jd b/docs/html/training/articles/keystore.jd
new file mode 100644
index 0000000..bbbda67
--- /dev/null
+++ b/docs/html/training/articles/keystore.jd
@@ -0,0 +1,107 @@
+page.title=Android Keystore System
+@jd:body
+
+<div id="qv-wrapper">
+  <div id="qv">
+    <h2>In this document</h2>
+    <ol>
+      <li><a href="#WhichShouldIUse">Choosing Between a Keychain or the Android Keystore Provider</a></li>
+      <li><a href="#UsingAndroidKeyStore">Using Android Keystore Provider
+      </a></li>
+      <ol>
+        <li><a href="#GeneratingANewPrivateKey">Generating a New Private Key</a></li>
+        <li><a href="#WorkingWithKeyStoreEntries">Working with Keystore Entries</a></li>
+        <li><a href="#ListingEntries">Listing Entries</a></li>
+        <li><a href="#SigningAndVerifyingData">Signing and Verifying Data</a></li>
+      </ol>
+    </ol>
+
+    <h2>Blog articles</h2>
+    <ol>
+      <li><a
+        href="http://android-developers.blogspot.com/2012/03/unifying-key-store-access-in-ics.html">
+          <h4>Unifying Key Store Access in ICS</h4>
+      </a></li>
+    </ol>
+  </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 Keystore system is used by the {@link
+  android.security.KeyChain} API as well as the Android
+  Keystore provider feature that was introduced in Android 4.3
+  (API level 18). This document goes over when and how to use the
+  Android Keystore provider.</p>
+
+<h2 id="WhichShouldIUse">Choosing Between a Keychain or the
+Android Keystore Provider</h2>
+
+<p>Use the {@link android.security.KeyChain} API when you want
+  system-wide credentials. When an app requests the use of any credential
+  through the {@link android.security.KeyChain} API, users get to
+  choose, through a system-provided UI, which of the installed credentials
+  an app can access. This allows several apps to use the
+  same set of credentials with user consent.</p>
+
+<p>Use the Android Keystore provider to let an individual app store its own
+  credentials that only the app itself can access.
+  This provides a way for apps to manage credentials that are usable
+  only by itself while providing the same security benefits that the
+  {@link android.security.KeyChain} API provides for system-wide
+  credentials. This method requires no user interaction to select the credentials.</p>
+
+<h2 id="UsingAndroidKeyStore">Using 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
+{@code AndroidKeyStore} provider introduced in Android 4.3 (API level 18).</p>
+
+<p>{@code AndroidKeyStore} is registered as a {@link
+  java.security.KeyStore} type for use with the {@link
+  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>
+
+<h3 id="GeneratingANewPrivateKey">Generating a New Private Key</h3>
+
+<p>Generating a new {@link java.security.PrivateKey} requires that
+  you also specify the initial X.509 attributes that the self-signed
+  certificate will have. You can replace the certificate at a later
+  time with a certificate signed by a Certificate Authority.</p>
+
+<p>To generate the key, use a {@link java.security.KeyPairGenerator}
+  with {@link android.security.KeyPairGeneratorSpec}:</p>
+
+{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java generate}
+
+<h3 id="WorkingWithKeyStoreEntries">Working with Keystore Entries</h3>
+
+<p>Using the {@code AndroidKeyStore} provider takes place through
+  all the standard {@link java.security.KeyStore} APIs.</p>
+
+<h4 id="ListingEntries">Listing Entries</h4>
+
+<p>List entries in the keystore by calling the {@link
+  java.security.KeyStore#aliases()} method:</p>
+
+{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java list}
+
+<h4 id="SigningAndVerifyingData">Signing and Verifying Data</h4>
+
+<p>Sign data by fetching the {@link
+  java.security.KeyStore.Entry} from the keystore and using the
+  {@link java.security.Signature} APIs, such as {@link
+  java.security.Signature#sign()}:</p>
+
+{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java sign}
+
+<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}