1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
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 cryptographic 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 key material
remaining non-exportable. Moreover, it offers facilities to restrict when and
how keys can be used, such as requiring user authentication for key use or
restricting encryption keys to be used only in certain block modes.</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} or
{@link javax.crypto.KeyGenerator} 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)} and {@link
javax.crypto.KeyGenerator#getInstance(String, String)
KeyGenerator.getInstance(algorithm, provider)} methods.</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="GeneratingANewSecretKey">Generating a New Secret Key</h3>
<p>To generate the key, use a {@link javax.crypto.KeyGenerator} with
{@link android.security.KeyGeneratorSpec}.
<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}
<h3 id="UserAuthentication">Requiring User Authentication For Key Use</h3>
<p>When generating or importing a key into the {@code AndroidKeyStore} you can specify that the key
can only be used if user has been authenticated. The user is authenticated using a subset of their
secure lock screen credentials. This is a security measure which makes it possible to generate
cryptographic assertions about the user having been authenticated.
<p>When a key is configured to require user authentication, it is also configured to operate in one
of the two modes:
<ul>
<li>User authentication is valid for a duration of time. All keys in this mode are authorized
for use as soon as the user unlocks the secure lock screen or confirms their secure lock screen
credentials using the {@link android.app.KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence) KeyguardManager.createConfirmDeviceCredentialIntent}
flow. Each key specifies for how long the authorization remains valid for that key. Such keys
can only be generated or imported if the secure lock screen is enabled (see {@link android.app.KeyguardManager#isDeviceSecure()}).
These keys become permanently invalidated once the secure lock screen is disabled or forcibly
reset (e.g. by a Device Admin).</li>
<li>User authentication is required for every use of the key. In this mode, a specific operation
involving a specific key is authorized by the user. Currently, the only means of such
authorization is fingerprint authentication: {@link android.hardware.fingerprint.FingerprintManager#authenticate(CryptoObject, CancellationSignal, AuthenticationCallback, int) FingerprintManager.authenticate}.
Such keys can only be generated or imported if at least one fingerprint is enrolled (see {@link android.hardware.fingerprint.FingerprintManager#hasEnrolledFingerprints() FingerprintManager.hasEnrolledFingerprints}).
These keys become permanently invalidated once all fingerprints are unenrolled.</li>
</ul>
|
