1page.title=Android Keystore System
2@jd:body
3
4<div id="qv-wrapper">
5  <div id="qv">
6    <h2>In this document</h2>
7    <ol>
8      <li><a href="#WhichShouldIUse">Choosing Between a Keychain or the Android Keystore Provider</a></li>
9      <li><a href="#UsingAndroidKeyStore">Using Android Keystore Provider
10      </a></li>
11      <ol>
12        <li><a href="#GeneratingANewPrivateKey">Generating a New Private Key</a></li>
13        <li><a href="#WorkingWithKeyStoreEntries">Working with Keystore Entries</a></li>
14        <li><a href="#ListingEntries">Listing Entries</a></li>
15        <li><a href="#SigningAndVerifyingData">Signing and Verifying Data</a></li>
16      </ol>
17    </ol>
18
19    <h2>Blog articles</h2>
20    <ol>
21      <li><a
22        href="http://android-developers.blogspot.com/2012/03/unifying-key-store-access-in-ics.html">
23          <h4>Unifying Key Store Access in ICS</h4>
24      </a></li>
25    </ol>
26  </div>
27</div>
28
29<p>The Android Keystore system lets you store private keys
30  in a container to make it more difficult to extract from the
31  device. Once keys are in the keystore, they can be used for
32  cryptographic operations with the private key material remaining
33  non-exportable.</p>
34
35<p>The Keystore system is used by the {@link
36  android.security.KeyChain} API as well as the Android
37  Keystore provider feature that was introduced in Android 4.3
38  (API level 18). This document goes over when and how to use the
39  Android Keystore provider.</p>
40
41<h2 id="WhichShouldIUse">Choosing Between a Keychain or the
42Android Keystore Provider</h2>
43
44<p>Use the {@link android.security.KeyChain} API when you want
45  system-wide credentials. When an app requests the use of any credential
46  through the {@link android.security.KeyChain} API, users get to
47  choose, through a system-provided UI, which of the installed credentials
48  an app can access. This allows several apps to use the
49  same set of credentials with user consent.</p>
50
51<p>Use the Android Keystore provider to let an individual app store its own
52  credentials that only the app itself can access.
53  This provides a way for apps to manage credentials that are usable
54  only by itself while providing the same security benefits that the
55  {@link android.security.KeyChain} API provides for system-wide
56  credentials. This method requires no user interaction to select the credentials.</p>
57
58<h2 id="UsingAndroidKeyStore">Using Android Keystore Provider</h2>
59
60<p>
61To use this feature, you use the standard {@link java.security.KeyStore}
62and {@link java.security.KeyPairGenerator} classes along with the
63{@code AndroidKeyStore} provider introduced in Android 4.3 (API level 18).</p>
64
65<p>{@code AndroidKeyStore} is registered as a {@link
66  java.security.KeyStore} type for use with the {@link
67  java.security.KeyStore#getInstance(String) KeyStore.getInstance(type)}
68  method and as a provider for use with the {@link
69  java.security.KeyPairGenerator#getInstance(String, String)
70  KeyPairGenerator.getInstance(algorithm, provider)} method.</p>
71
72<h3 id="GeneratingANewPrivateKey">Generating a New Private Key</h3>
73
74<p>Generating a new {@link java.security.PrivateKey} requires that
75  you also specify the initial X.509 attributes that the self-signed
76  certificate will have. You can replace the certificate at a later
77  time with a certificate signed by a Certificate Authority.</p>
78
79<p>To generate the key, use a {@link java.security.KeyPairGenerator}
80  with {@link android.security.KeyPairGeneratorSpec}:</p>
81
82{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java generate}
83
84<h3 id="WorkingWithKeyStoreEntries">Working with Keystore Entries</h3>
85
86<p>Using the {@code AndroidKeyStore} provider takes place through
87  all the standard {@link java.security.KeyStore} APIs.</p>
88
89<h4 id="ListingEntries">Listing Entries</h4>
90
91<p>List entries in the keystore by calling the {@link
92  java.security.KeyStore#aliases()} method:</p>
93
94{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java list}
95
96<h4 id="SigningAndVerifyingData">Signing and Verifying Data</h4>
97
98<p>Sign data by fetching the {@link
99  java.security.KeyStore.Entry} from the keystore and using the
100  {@link java.security.Signature} APIs, such as {@link
101  java.security.Signature#sign()}:</p>
102
103{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java sign}
104
105<p>Similarly, verify data with the {@link java.security.Signature#verify(byte[])} method:</p>
106
107{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java verify}
108