204 lines
11 KiB
Plaintext
204 lines
11 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="#SecurityFeatures">Security Features</a></li>
|
|
<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. See
|
|
<a href="#SecurityFeatures">Security Features</a> section for more information.</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="SecurityFeatures">Security Features</h2>
|
|
|
|
Android Keystore system protects key material from unauthorized use. Firstly, Android Keystore
|
|
mitigates unauthorized use of key material outside of the Android device by preventing extraction of
|
|
the key material from application processes and from the Android device as a whole. Secondly,
|
|
Android KeyStore mitigates unauthorized use of key material on the Android device by making apps
|
|
specify authorized uses of their keys and then enforcing these restrictions.
|
|
|
|
<h3 id="ExtractionPrevention">Extraction Prevention</h3>
|
|
|
|
Key material of Android Keystore keys is protected from extraction using two security measures:
|
|
<ul>
|
|
<li>Key material never enters the application process. When an application performs cryptographic
|
|
operations using an Android Keystore key, behind the scenes plaintext, ciphertext, and messages to
|
|
be signed or verified are fed to a system process which carries out the cryptographic operations.
|
|
If the app's process is compromised, the attacker may be able to use the app's keys but will not
|
|
be able to extract their key material (for example, to be used outside of the Android device).
|
|
</li>
|
|
<li>Key material may be bound to the secure hardware (e.g., Trusted Execution Environment (TEE),
|
|
Secure Element (SE)) of the Android device. When this feature is enabled for a key, its key
|
|
material is never exposed outside of secure hardware. If the Android OS is compromised or an
|
|
attacker can read the device's internal storage, the attacker may be able to use any app's Android
|
|
Keystore keys on the Android device, but not extract them from the device. This feature is enabled
|
|
only if the device's secure hardware supports the particular combination of key algorithm, block
|
|
modes, padding schemes, and digests with which the key is authorized to be used. To check whether
|
|
the feature is enabled for a key, obtain a {@link android.security.keystore.KeyInfo} for the key
|
|
and inspect the return value of
|
|
{@link android.security.keystore.KeyInfo#isInsideSecureHardware() KeyInfo.isInsideSecurityHardware()}.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 id="KeyUseAuthorizations">Key Use Authorizations</h3>
|
|
|
|
To mitigate unauthorized use of keys on the Android device, Android Keystore lets apps specify
|
|
authorized uses of their keys when generating or importing the keys. Once a key is generated or
|
|
imported, its authorizations can not be changed. Authorizations are then enforced by the Android
|
|
Keystore whenever the key is used.
|
|
|
|
<p>Supported key use authorizations fall into the following categories:
|
|
<ul>
|
|
<li><em>cryptography</em>: authorized key algorithm, operations or purposes (encrypt, decrypt, sign,
|
|
verify), padding schemes, block modes, digests with which the key can be used</li>
|
|
<li><em>temporal validity interval</em>: interval of time during which the key is authorized for
|
|
use</li>
|
|
<li><em>user authentication</em>: the key can only be used if the user has been authenticated
|
|
recently enough. See <a href="#UserAuthentication">Requiring User Authentication For Key Use</a>.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>As an additional security measure, for keys whose key material is inside secure hardware (see
|
|
{@link android.security.keystore.KeyInfo#isInsideSecureHardware() KeyInfo.isInsideSecurityHardware()})
|
|
some key use authorizations may be enforced by secure hardware, depending on the Android device.
|
|
Cryptographic and user authentication authorizations are likely to be enforced by secure hardware.
|
|
Temporal validity interval authorizations are unlikely to be enforced by the secure hardware
|
|
because it normally does not have an independent secure real-time clock.
|
|
|
|
<p>Whether a key's user authentication authorization is enforced by the secure hardware can be
|
|
queried using
|
|
{@link android.security.keystore.KeyInfo#isUserAuthenticationRequirementEnforcedBySecureHardware() KeyInfo.isUserAuthenticationRequirementEnforcedBySecureHardware()}.
|
|
|
|
<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.keystore.KeyGenParameterSpec}.
|
|
|
|
<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() 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, int, AuthenticationCallback, Handler) 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>
|