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.
+ +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.
+ +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.
+ +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.
+ ++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).
+ +{@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.
+ +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.
+ +To generate the key, use a {@link java.security.KeyPairGenerator} + with {@link android.security.KeyPairGeneratorSpec}:
+ +{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java generate} + +Using the {@code AndroidKeyStore} provider takes place through + all the standard {@link java.security.KeyStore} APIs.
+ +List entries in the keystore by calling the {@link + java.security.KeyStore#aliases()} method:
+ +{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java list} + +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()}:
+ +{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java sign} + +Similarly, verify data with the {@link java.security.Signature#verify(byte[])} method:
+ +{@sample development/samples/ApiDemos/src/com/example/android/apis/security/KeyStoreUsage.java verify} diff --git a/keystore/java/android/security/KeyPairGeneratorSpec.java b/keystore/java/android/security/KeyPairGeneratorSpec.java index 59f89bcb6cb2b..418e4e79ea8c4 100644 --- a/keystore/java/android/security/KeyPairGeneratorSpec.java +++ b/keystore/java/android/security/KeyPairGeneratorSpec.java @@ -30,7 +30,7 @@ import javax.security.auth.x500.X500Principal; /** * This provides the required parameters needed for initializing the * {@code KeyPairGenerator} that works with - * Android KeyStore + * Android KeyStore * facility. 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. ** This will build a parameter spec for use with the Android KeyStore facility. + * training/articles/keystore.html">Android KeyStore facility. *
* The required fields must be filled in with the builder. *
diff --git a/keystore/java/android/security/KeyStoreParameter.java b/keystore/java/android/security/KeyStoreParameter.java index 621a605074b63..fb5c859351cda 100644 --- a/keystore/java/android/security/KeyStoreParameter.java +++ b/keystore/java/android/security/KeyStoreParameter.java @@ -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 - * Android KeyStore + * Android KeyStore * facility. 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. *
* This will build protection parameters for use with the - * Android KeyStore + * Android KeyStore * facility. *
* This can be used to require that KeyStore entries be stored encrypted.