# Print output for @column tags ?> KeyChain - Android SDK | Android Developers

Most visited

Recently visited

KeyChain

public final class KeyChain
extends Object

java.lang.Object
   ↳ android.security.KeyChain


The KeyChain class provides access to private keys and their corresponding certificate chains in credential storage.

Applications accessing the KeyChain normally go through these steps:

  1. Receive a callback from an X509KeyManager that a private key is requested.
  2. Call choosePrivateKeyAlias to allow the user to select from a list of currently available private keys and corresponding certificate chains. The chosen alias will be returned by the callback KeyChainAliasCallback#alias, or null if no private key is available or the user cancels the request.
  3. Call getPrivateKey(Context, String) and getCertificateChain(Context, String) to retrieve the credentials to return to the corresponding X509KeyManager callbacks.

An application may remember the value of a selected alias to avoid prompting the user with choosePrivateKeyAlias on subsequent connections. If the alias is no longer valid, null will be returned on lookups using that value

An application can request the installation of private keys and certificates via the Intent provided by createInstallIntent(). Private keys installed via this Intent will be accessible via choosePrivateKeyAlias(Activity, KeyChainAliasCallback, String[], Principal[], Uri, String) while Certificate Authority (CA) certificates will be trusted by all applications through the default X509TrustManager.

Summary

Constants

String ACTION_KEYCHAIN_CHANGED

Broadcast Action: Indicates the contents of the keychain has changed.

String ACTION_KEY_ACCESS_CHANGED

Broadcast Action: Indicates that the access permissions for a private key have changed.

String ACTION_STORAGE_CHANGED

This constant is deprecated. Use ACTION_KEYCHAIN_CHANGED, ACTION_TRUST_STORE_CHANGED or ACTION_KEY_ACCESS_CHANGED. Apps that target a version higher than Build.VERSION_CODES.N_MR1 will only receive this broadcast if they register for it at runtime.

String ACTION_TRUST_STORE_CHANGED

Broadcast Action: Indicates the contents of the trusted certificate store has changed.

String EXTRA_CERTIFICATE

Optional extra to specify an X.509 certificate to install on the Intent returned by createInstallIntent().

String EXTRA_KEY_ACCESSIBLE

Used as a boolean extra field in ACTION_KEY_ACCESS_CHANGED to supply if the key is accessible to the application.

String EXTRA_KEY_ALIAS

Used as a String extra field in ACTION_KEY_ACCESS_CHANGED to supply the alias of the key.

String EXTRA_NAME

Optional extra to specify a String credential name on the Intent returned by createInstallIntent().

String EXTRA_PKCS12

Optional extra for use with the Intent returned by createInstallIntent() to specify a PKCS#12 key store to install.

String KEY_ALIAS_SELECTION_DENIED

Used by DPC or delegated app in DeviceAdminReceiver.onChoosePrivateKeyAlias(Context, Intent, int, Uri, String) or DelegatedAdminReceiver.onChoosePrivateKeyAlias(Context, Intent, int, Uri, String) to identify that the requesting app is not granted access to any key, and nor will the user be able to grant access manually.

Public constructors

KeyChain()

Public methods

static void choosePrivateKeyAlias(Activity activity, KeyChainAliasCallback response, String[] keyTypes, Principal[] issuers, String host, int port, String alias)

Launches an Activity for the user to select the alias for a private key and certificate pair for authentication.

static void choosePrivateKeyAlias(Activity activity, KeyChainAliasCallback response, String[] keyTypes, Principal[] issuers, Uri uri, String alias)

Launches an Activity for the user to select the alias for a private key and certificate pair for authentication.

static Intent createInstallIntent()

Returns an Intent that can be used for credential installation.

static X509Certificate[] getCertificateChain(Context context, String alias)

Returns the X509Certificate chain for the requested alias, or null if the alias does not exist or the caller has no permission to access it (see note on exceptions in getPrivateKey(Context, String)).

static PrivateKey getPrivateKey(Context context, String alias)

Returns the PrivateKey for the requested alias, or null if the alias does not exist or the caller has no permission to access it (see note on exceptions below).

static boolean isBoundKeyAlgorithm(String algorithm)

This method is deprecated. Whether the key is bound to the secure hardware is known only once the key has been imported. To find out, use:

PrivateKey key = ...; // private key from KeyChain

 KeyFactory keyFactory =
     KeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
 KeyInfo keyInfo = keyFactory.getKeySpec(key, KeyInfo.class);
 if (keyInfo.isInsideSecureHardware()) {
     // The key is bound to the secure hardware of this Android
 }

static boolean isKeyAlgorithmSupported(String algorithm)

Returns true if the current device's KeyChain supports a specific PrivateKey type indicated by algorithm (e.g., "RSA").

Inherited methods

Constants

ACTION_KEYCHAIN_CHANGED

public static final String ACTION_KEYCHAIN_CHANGED

Broadcast Action: Indicates the contents of the keychain has changed. Sent when a KeyChain entry is added, modified or removed.

Constant Value: "android.security.action.KEYCHAIN_CHANGED"

ACTION_KEY_ACCESS_CHANGED

public static final String ACTION_KEY_ACCESS_CHANGED

Broadcast Action: Indicates that the access permissions for a private key have changed.

Constant Value: "android.security.action.KEY_ACCESS_CHANGED"

ACTION_STORAGE_CHANGED

public static final String ACTION_STORAGE_CHANGED

This constant is deprecated.
Use ACTION_KEYCHAIN_CHANGED, ACTION_TRUST_STORE_CHANGED or ACTION_KEY_ACCESS_CHANGED. Apps that target a version higher than Build.VERSION_CODES.N_MR1 will only receive this broadcast if they register for it at runtime.

Broadcast Action: Indicates the trusted storage has changed. Sent when one of this happens:

  • a new CA is added,
  • an existing CA is removed or disabled,
  • a disabled CA is enabled,
  • trusted storage is reset (all user certs are cleared),
  • when permission to access a private key is changed.

Constant Value: "android.security.STORAGE_CHANGED"

ACTION_TRUST_STORE_CHANGED

public static final String ACTION_TRUST_STORE_CHANGED

Broadcast Action: Indicates the contents of the trusted certificate store has changed. Sent when one the following occurs:

  • A pre-installed CA is disabled or re-enabled
  • A CA is added or removed from the trust store

Constant Value: "android.security.action.TRUST_STORE_CHANGED"

EXTRA_CERTIFICATE

public static final String EXTRA_CERTIFICATE

Optional extra to specify an X.509 certificate to install on the Intent returned by createInstallIntent(). The extra value should be a PEM or ASN.1 DER encoded byte[]. An X509Certificate can be converted to DER encoded bytes with X509Certificate#getEncoded.

EXTRA_NAME may be used to provide a default alias name for the installed certificate.

Constant Value: "CERT"

EXTRA_KEY_ACCESSIBLE

public static final String EXTRA_KEY_ACCESSIBLE

Used as a boolean extra field in ACTION_KEY_ACCESS_CHANGED to supply if the key is accessible to the application.

Constant Value: "android.security.extra.KEY_ACCESSIBLE"

EXTRA_KEY_ALIAS

public static final String EXTRA_KEY_ALIAS

Used as a String extra field in ACTION_KEY_ACCESS_CHANGED to supply the alias of the key.

Constant Value: "android.security.extra.KEY_ALIAS"

EXTRA_NAME

public static final String EXTRA_NAME

Optional extra to specify a String credential name on the Intent returned by createInstallIntent().

Constant Value: "name"

EXTRA_PKCS12

public static final String EXTRA_PKCS12

Optional extra for use with the Intent returned by createInstallIntent() to specify a PKCS#12 key store to install. The extra value should be a byte[]. The bytes may come from an external source or be generated with KeyStore.store(OutputStream, char[]) on a "PKCS12" instance.

The user will be prompted for the password to load the key store.

The key store will be scanned for KeyStore.PrivateKeyEntry entries and both the private key and associated certificate chain will be installed.

EXTRA_NAME may be used to provide a default alias name for the installed credentials.

Constant Value: "PKCS12"

KEY_ALIAS_SELECTION_DENIED

public static final String KEY_ALIAS_SELECTION_DENIED

Used by DPC or delegated app in DeviceAdminReceiver.onChoosePrivateKeyAlias(Context, Intent, int, Uri, String) or DelegatedAdminReceiver.onChoosePrivateKeyAlias(Context, Intent, int, Uri, String) to identify that the requesting app is not granted access to any key, and nor will the user be able to grant access manually.

Constant Value: "android:alias-selection-denied"

Public constructors

KeyChain

public KeyChain ()

Public methods

choosePrivateKeyAlias

public static void choosePrivateKeyAlias (Activity activity, 
                KeyChainAliasCallback response, 
                String[] keyTypes, 
                Principal[] issuers, 
                String host, 
                int port, 
                String alias)

Launches an Activity for the user to select the alias for a private key and certificate pair for authentication. The selected alias or null will be returned via the KeyChainAliasCallback callback.

A device policy controller (as a device or profile owner) can intercept the request before the activity is shown, to pick a specific private key alias by implementing onChoosePrivateKeyAlias.

keyTypes and issuers may be used to narrow down suggested choices to the user. If either keyTypes or issuers is specified and non-empty, and there are no matching certificates in the KeyChain, then the certificate selection prompt would be suppressed entirely.

host and port may be used to give the user more context about the server requesting the credentials.

alias allows the caller to preselect an existing alias which will still be subject to user confirmation.

Parameters
activity Activity: The Activity context to use for launching the new sub-Activity to prompt the user to select a private key; used only to call startActivity(); must not be null. This value cannot be null.

response KeyChainAliasCallback: Callback to invoke when the request completes; must not be null. This value cannot be null.

keyTypes String: The acceptable types of asymmetric keys such as "RSA", "EC" or null. This value may be null. Value is KeyProperties.KEY_ALGORITHM_RSA, KeyProperties.KEY_ALGORITHM_EC, KeyProperties.KEY_ALGORITHM_AES, KeyProperties.KEY_ALGORITHM_HMAC_SHA1, KeyProperties.KEY_ALGORITHM_HMAC_SHA224, KeyProperties.KEY_ALGORITHM_HMAC_SHA256, KeyProperties.KEY_ALGORITHM_HMAC_SHA384, or KeyProperties.KEY_ALGORITHM_HMAC_SHA512

issuers Principal: The acceptable certificate issuers for the certificate matching the private key, or null. This value may be null.

host String: The host name of the server requesting the certificate, or null if unavailable. This value may be null.

port int: The port number of the server requesting the certificate, or -1 if unavailable.

alias String: The alias to preselect if available, or null if unavailable. This value may be null.

choosePrivateKeyAlias

public static void choosePrivateKeyAlias (Activity activity, 
                KeyChainAliasCallback response, 
                String[] keyTypes, 
                Principal[] issuers, 
                Uri uri, 
                String alias)

Launches an Activity for the user to select the alias for a private key and certificate pair for authentication. The selected alias or null will be returned via the KeyChainAliasCallback callback.

A device policy controller (as a device or profile owner) can intercept the request before the activity is shown, to pick a specific private key alias by implementing onChoosePrivateKeyAlias.

keyTypes and issuers may be used to narrow down suggested choices to the user. If either keyTypes or issuers is specified and non-empty, and there are no matching certificates in the KeyChain, then the certificate selection prompt would be suppressed entirely.

uri may be used to give the user more context about the server requesting the credentials.

alias allows the caller to preselect an existing alias which will still be subject to user confirmation.

Parameters
activity Activity: The Activity context to use for launching the new sub-Activity to prompt the user to select a private key; used only to call startActivity(); must not be null. This value cannot be null.

response KeyChainAliasCallback: Callback to invoke when the request completes; must not be null. This value cannot be null.

keyTypes String: The acceptable types of asymmetric keys such as "RSA", "EC" or null. This value may be null. Value is KeyProperties.KEY_ALGORITHM_RSA, KeyProperties.KEY_ALGORITHM_EC, KeyProperties.KEY_ALGORITHM_AES, KeyProperties.KEY_ALGORITHM_HMAC_SHA1, KeyProperties.KEY_ALGORITHM_HMAC_SHA224, KeyProperties.KEY_ALGORITHM_HMAC_SHA256, KeyProperties.KEY_ALGORITHM_HMAC_SHA384, or KeyProperties.KEY_ALGORITHM_HMAC_SHA512

issuers Principal: The acceptable certificate issuers for the certificate matching the private key, or null. This value may be null.

uri Uri: The full URI the server is requesting the certificate for, or null if unavailable. This value may be null.

alias String: The alias to preselect if available, or null if unavailable. This value may be null.

Throws
IllegalArgumentException if the specified issuers are not of type X500Principal.

createInstallIntent

public static Intent createInstallIntent ()

Returns an Intent that can be used for credential installation. The intent may be used without any extras, in which case the user will be able to install credentials from their own source.

Alternatively, EXTRA_CERTIFICATE or EXTRA_PKCS12 maybe used to specify the bytes of an X.509 certificate or a PKCS#12 key store for installation. These extras may be combined with EXTRA_NAME to provide a default alias name for credentials being installed.

When used with Activity#startActivityForResult, Activity#RESULT_OK will be returned if a credential was successfully installed, otherwise Activity#RESULT_CANCELED will be returned.

Starting from Build.VERSION_CODES.R, the intent returned by this method cannot be used for installing CA certificates. Since CA certificates can only be installed via Settings, the app should provide the user with a file containing the CA certificate. One way to do this would be to use the MediaStore API to write the certificate to the MediaStore.Downloads collection.

Returns
Intent This value cannot be null.

getCertificateChain

public static X509Certificate[] getCertificateChain (Context context, 
                String alias)

Returns the X509Certificate chain for the requested alias, or null if the alias does not exist or the caller has no permission to access it (see note on exceptions in getPrivateKey(Context, String)).

Note: If a certificate chain was explicitly specified when the alias was installed, this method will return that chain. If only the client certificate was specified at the installation time, this method will try to build a certificate chain using all available trust anchors (preinstalled and user-added).

This method may block while waiting for a connection to another process, and must never be called from the main thread.

As Activity and Service contexts are short-lived and can be destroyed at any time from the main thread, it is safer to rely on a long-lived context such as one returned from Context#getApplicationContext().

In case the caller specifies an alias for which it lacks a grant, it must call choosePrivateKeyAlias(Activity, KeyChainAliasCallback, String[], Principal[], Uri, String) again. See getPrivateKey(Context, String) for more details on coping with this scenario.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
context Context: This value cannot be null.

alias String: The alias of the desired certificate chain, typically returned via KeyChainAliasCallback#alias. This value cannot be null.

Returns
X509Certificate[]

Throws
KeyChainException if the alias was valid but there was some problem accessing it.
IllegalStateException if called from the main thread.
InterruptedException

getPrivateKey

public static PrivateKey getPrivateKey (Context context, 
                String alias)

Returns the PrivateKey for the requested alias, or null if the alias does not exist or the caller has no permission to access it (see note on exceptions below).

This method may block while waiting for a connection to another process, and must never be called from the main thread.

As Activity and Service contexts are short-lived and can be destroyed at any time from the main thread, it is safer to rely on a long-lived context such as one returned from Context#getApplicationContext().

If the caller provides a valid alias to which it was not granted access, then the caller must invoke choosePrivateKeyAlias(Activity, KeyChainAliasCallback, String[], Principal[], Uri, String) again to get another valid alias or a grant to access the same alias.

On Android versions prior to Q, when a key associated with the specified alias is unavailable, the method will throw a KeyChainException rather than return null. If the exception's cause (as obtained by calling KeyChainException.getCause()) is a throwable of type IllegalStateException then the caller lacks a grant to access the key and certificates associated with this alias.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
context Context: This value cannot be null.

alias String: The alias of the desired private key, typically returned via KeyChainAliasCallback#alias. This value cannot be null.

Returns
PrivateKey

Throws
KeyChainException if the alias was valid but there was some problem accessing it.
IllegalStateException if called from the main thread.
InterruptedException

isBoundKeyAlgorithm

public static boolean isBoundKeyAlgorithm (String algorithm)

This method is deprecated.
Whether the key is bound to the secure hardware is known only once the key has been imported. To find out, use:

PrivateKey key = ...; // private key from KeyChain

 KeyFactory keyFactory =
     KeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
 KeyInfo keyInfo = keyFactory.getKeySpec(key, KeyInfo.class);
 if (keyInfo.isInsideSecureHardware()) {
     // The key is bound to the secure hardware of this Android
 }

Returns true if the current device's KeyChain binds any PrivateKey of the given algorithm to the device once imported or generated. This can be used to tell if there is special hardware support that can be used to bind keys to the device in a way that makes it non-exportable.

Parameters
algorithm String: This value cannot be null. Value is KeyProperties.KEY_ALGORITHM_RSA, KeyProperties.KEY_ALGORITHM_EC, KeyProperties.KEY_ALGORITHM_AES, KeyProperties.KEY_ALGORITHM_HMAC_SHA1, KeyProperties.KEY_ALGORITHM_HMAC_SHA224, KeyProperties.KEY_ALGORITHM_HMAC_SHA256, KeyProperties.KEY_ALGORITHM_HMAC_SHA384, or KeyProperties.KEY_ALGORITHM_HMAC_SHA512

Returns
boolean

isKeyAlgorithmSupported

public static boolean isKeyAlgorithmSupported (String algorithm)

Returns true if the current device's KeyChain supports a specific PrivateKey type indicated by algorithm (e.g., "RSA").

Parameters
algorithm String: This value cannot be null. Value is KeyProperties.KEY_ALGORITHM_RSA, KeyProperties.KEY_ALGORITHM_EC, KeyProperties.KEY_ALGORITHM_AES, KeyProperties.KEY_ALGORITHM_HMAC_SHA1, KeyProperties.KEY_ALGORITHM_HMAC_SHA224, KeyProperties.KEY_ALGORITHM_HMAC_SHA256, KeyProperties.KEY_ALGORITHM_HMAC_SHA384, or KeyProperties.KEY_ALGORITHM_HMAC_SHA512

Returns
boolean