716cc7dcac
Add exposition about the use cases for AndroidKeyStore and links to the API sample application for different use cases. Bug: 8608817 Change-Id: Ic4ce9405781c92f12687895b28c671661ea5524f
108 lines
4.5 KiB
Plaintext
108 lines
4.5 KiB
Plaintext
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}
|