Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 716cc7dc authored by Robert Ly's avatar Robert Ly
Browse files

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
parent ab642495

docs/html/training/articles/keystore.jd

0 → 100644
+107 −0
Original line number Diff line number Diff line 
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}

keystore/java/android/security/KeyPairGeneratorSpec.java

+2 −2
Original line number Diff line number Diff line
@@ -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>

keystore/java/android/security/KeyStoreParameter.java

+2 −2
Original line number Diff line number Diff line
@@ -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.