diff options
| -rw-r--r-- | docs/html/training/articles/keystore.jd | 107 | ||||
| -rw-r--r-- | keystore/java/android/security/KeyPairGeneratorSpec.java | 4 | ||||
| -rw-r--r-- | keystore/java/android/security/KeyStoreParameter.java | 4 |
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 59f89bc..418e4e7 100644 --- a/keystore/java/android/security/KeyPairGeneratorSpec.java +++ b/keystore/java/android/security/KeyPairGeneratorSpec.java @@ -30,7 +30,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 @@ -187,7 +187,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. |