to top
Android APIs
public final class

KeyChain

extends Object
java.lang.Object
   ↳ android.security.KeyChain

Class Overview

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 alias(String), 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[], String, int, String) while Certificate Authority (CA) certificates will be trusted by all applications through the default X509TrustManager.

Summary

Constants
String ACTION_STORAGE_CHANGED Broadcast Action: Indicates the trusted storage has changed.
String EXTRA_CERTIFICATE Optional extra to specify an X.509 certificate to install on the Intent returned by createInstallIntent().
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.
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 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 no there is no result.
static PrivateKey getPrivateKey(Context context, String alias)
Returns the PrivateKey for the requested alias, or null if no there is no result.
static boolean isBoundKeyAlgorithm(String algorithm)
Returns true if the current device's KeyChain binds any PrivateKey of the given algorithm to the device once imported or generated.
static boolean isKeyAlgorithmSupported(String algorithm)
Returns true if the current device's KeyChain supports a specific PrivateKey type indicated by algorithm (e.g., "RSA").
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_STORAGE_CHANGED

Added in API level 16

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"

public static final String EXTRA_CERTIFICATE

Added in API level 14

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 getEncoded().

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

Constant Value: "CERT"

public static final String EXTRA_NAME

Added in API level 14

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

Constant Value: "name"

public static final String EXTRA_PKCS12

Added in API level 14

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 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"

Public Constructors

public KeyChain ()

Added in API level 14

Public Methods

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

Added in API level 14

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.

keyTypes and issuers may be used to highlight suggested choices to the user, although to cope with sometimes erroneous values provided by servers, the user may be able to override these suggestions.

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

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

Parameters
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.
response Callback to invoke when the request completes; must not be null
keyTypes The acceptable types of asymmetric keys such as "RSA" or "DSA", or a null array.
issuers The acceptable certificate issuers for the certificate matching the private key, or null.
host The host name of the server requesting the certificate, or null if unavailable.
port The port number of the server requesting the certificate, or -1 if unavailable.
alias The alias to preselect if available, or null if unavailable.

public static Intent createInstallIntent ()

Added in API level 14

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 startActivityForResult(Intent, int), RESULT_OK will be returned if a credential was successfully installed, otherwise RESULT_CANCELED will be returned.

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

Added in API level 14

Returns the X509Certificate chain for the requested alias, or null if no there is no result.

Parameters
alias The alias of the desired certificate chain, typically returned via alias(String).
Throws
KeyChainException if the alias was valid but there was some problem accessing it.
InterruptedException

public static PrivateKey getPrivateKey (Context context, String alias)

Added in API level 14

Returns the PrivateKey for the requested alias, or null if no there is no result.

Parameters
alias The alias of the desired private key, typically returned via alias(String).
Throws
KeyChainException if the alias was valid but there was some problem accessing it.
InterruptedException

public static boolean isBoundKeyAlgorithm (String algorithm)

Added in API level 18

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.

public static boolean isKeyAlgorithmSupported (String algorithm)

Added in API level 18

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