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
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}
diff --git a/keystore/java/android/security/KeyPairGeneratorSpec.java b/keystore/java/android/security/KeyPairGeneratorSpec.java
index 59f89bc..418e4e7 100644
--- a/keystore/java/android/security/KeyPairGeneratorSpec.java
+++ b/keystore/java/android/security/KeyPairGeneratorSpec.java
@@ -30,7 +30,7 @@
/**
* This provides the required parameters needed for initializing the
* {@code KeyPairGenerator} that works with
- * <a href="{@docRoot}guide/topics/security/keystore.html">Android KeyStore
+ * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore
* facility</a>. The Android KeyStore facility is accessed through a
* {@link java.security.KeyPairGenerator} API using the {@code AndroidKeyStore}
* provider. The {@code context} passed in may be used to pop up some UI to ask
@@ -187,7 +187,7 @@
* Builder class for {@link KeyPairGeneratorSpec} objects.
* <p>
* This will build a parameter spec for use with the <a href="{@docRoot}
- * guide/topics/security/keystore.html">Android KeyStore facility</a>.
+ * training/articles/keystore.html">Android KeyStore facility</a>.
* <p>
* The required fields must be filled in with the builder.
* <p>
diff --git a/keystore/java/android/security/KeyStoreParameter.java b/keystore/java/android/security/KeyStoreParameter.java
index 621a605..fb5c859 100644
--- a/keystore/java/android/security/KeyStoreParameter.java
+++ b/keystore/java/android/security/KeyStoreParameter.java
@@ -27,7 +27,7 @@
/**
* This provides the optional parameters that can be specified for
* {@code KeyStore} entries that work with
- * <a href="{@docRoot}guide/topics/security/keystore.html">Android KeyStore
+ * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore
* facility</a>. The Android KeyStore facility is accessed through a
* {@link java.security.KeyStore} API using the {@code AndroidKeyStore}
* provider. The {@code context} passed in may be used to pop up some UI to ask
@@ -70,7 +70,7 @@
* Builder class for {@link KeyStoreParameter} objects.
* <p>
* This will build protection parameters for use with the
- * <a href="{@docRoot}guide/topics/security/keystore.html">Android KeyStore
+ * <a href="{@docRoot}training/articles/keystore.html">Android KeyStore
* facility</a>.
* <p>
* This can be used to require that KeyStore entries be stored encrypted.