am f3cecfa2: am 55d525b2: am 716cc7dc: Add documentation for AndroidKeyStore

* commit 'f3cecfa2185ef5622992b21da8204b8b6590ef2d':
  Add documentation for AndroidKeyStore

3 files changed, 111 insertions, 4 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}
diff --git a/keystore/java/android/security/KeyPairGeneratorSpec.java b/keystore/java/android/security/KeyPairGeneratorSpec.java
index 21d6caa..4a823cc 100644
--- a/keystore/java/android/security/KeyPairGeneratorSpec.java
+++ b/keystore/java/android/security/KeyPairGeneratorSpec.java
@@ -35,7 +35,7 @@ import javax.security.auth.x500.X500Principal;
 /**
  * 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
@@ -306,7 +306,7 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
      * 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 @@ import java.security.cert.Certificate;
 /**
  * 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 @@ public final class KeyStoreParameter implements ProtectionParameter {
      * 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.