public final class KeyChain extends Object
KeyChain
class provides access to private keys and
their corresponding certificate chains in credential storage.
Applications accessing the KeyChain
normally go through
these steps:
X509KeyManager
that a private key is requested.
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(java.lang.String)
, or null if no private
key is available or the user cancels the request.
getPrivateKey(android.content.Context, java.lang.String)
and getCertificateChain(android.content.Context, java.lang.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(android.app.Activity, android.security.KeyChainAliasCallback, java.lang.String[], java.security.Principal[], java.lang.String, int, java.lang.String)
while
Certificate Authority (CA) certificates will be trusted by all
applications through the default X509TrustManager
.
Modifier and Type | Class and Description |
---|---|
static class |
KeyChain.KeyChainConnection |
Modifier and Type | Field and Description |
---|---|
static String |
ACCOUNT_TYPE |
static String |
ACTION_STORAGE_CHANGED
Broadcast Action: Indicates the trusted storage has changed.
|
static String |
EXTRA_ALIAS
Extra for use with
ACTION_CHOOSER |
static String |
EXTRA_CERTIFICATE
Optional extra to specify an X.509 certificate to install on
the
Intent returned by createInstallIntent() . |
static String |
EXTRA_NAME
|
static String |
EXTRA_PKCS12
Optional extra for use with the
Intent returned by
createInstallIntent() to specify a PKCS#12 key store to
install. |
static String |
EXTRA_RESPONSE
Extra for use with
ACTION_CHOOSER |
static String |
EXTRA_SENDER
Extra for use with
ACTION_CHOOSER |
static String |
EXTRA_URI
Extra for use with
ACTION_CHOOSER |
Constructor and Description |
---|
KeyChain() |
Modifier and Type | Method and Description |
---|---|
static KeyChain.KeyChainConnection |
bind(Context context) |
static KeyChain.KeyChainConnection |
bindAsUser(Context context,
UserHandle user) |
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 there is no result. |
static PrivateKey |
getPrivateKey(Context context,
String alias)
Returns the
PrivateKey for the requested alias, or null
if there is no result. |
static boolean |
isBoundKeyAlgorithm(String algorithm)
Deprecated.
Whether the key is bound to the secure hardware is known only
once the key has been imported. To find out, use:
|
static boolean |
isKeyAlgorithmSupported(String algorithm)
Returns
true if the current device's KeyChain supports a
specific PrivateKey type indicated by algorithm (e.g.,
"RSA"). |
static X509Certificate |
toCertificate(byte[] bytes) |
static Collection<X509Certificate> |
toCertificates(byte[] bytes) |
public static final String ACCOUNT_TYPE
public static final String EXTRA_RESPONSE
ACTION_CHOOSER
public static final String EXTRA_URI
ACTION_CHOOSER
public static final String EXTRA_ALIAS
ACTION_CHOOSER
public static final String EXTRA_SENDER
ACTION_CHOOSER
public static final String EXTRA_NAME
public static final String EXTRA_CERTIFICATE
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 Certificate.getEncoded()
.
EXTRA_NAME
may be used to provide a default alias
name for the installed certificate.
public static final String EXTRA_PKCS12
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(java.io.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.
public static final String ACTION_STORAGE_CHANGED
public static Intent createInstallIntent()
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(android.content.Intent, int)
,
Activity.RESULT_OK
will be returned if a credential was
successfully installed, otherwise Activity.RESULT_CANCELED
will be returned.
public static void choosePrivateKeyAlias(Activity activity, KeyChainAliasCallback response, String[] keyTypes, Principal[] issuers, String host, int port, String alias)
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.
The device or profile owner can intercept this before the activity is shown, to pick a specific private key alias.
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.
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 nullkeyTypes
- 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 void choosePrivateKeyAlias(Activity activity, KeyChainAliasCallback response, String[] keyTypes, Principal[] issuers, Uri uri, String alias)
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.
The device or profile owner can intercept this before the activity is shown, to pick a specific private key alias.
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.
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 nullkeyTypes
- The acceptable types of asymmetric keys such as
"EC" or "RSA", or a null array.issuers
- The acceptable certificate issuers for the
certificate matching the private key, or null.uri
- The full URI the server is requesting the certificate
for, or null if unavailable.alias
- The alias to preselect if available, or null if
unavailable.public static PrivateKey getPrivateKey(Context context, String alias) throws KeyChainException, InterruptedException
PrivateKey
for the requested alias, or null
if there is no result.
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()
.
alias
- The alias of the desired private key, typically returned via
KeyChainAliasCallback.alias(java.lang.String)
.KeyChainException
- if the alias was valid but there was some problem accessing it.IllegalStateException
- if called from the main thread.InterruptedException
public static X509Certificate[] getCertificateChain(Context context, String alias) throws KeyChainException, InterruptedException
X509Certificate
chain for the requested
alias, or null if there is no result.
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()
.
alias
- The alias of the desired certificate chain, typically
returned via KeyChainAliasCallback.alias(java.lang.String)
.KeyChainException
- if the alias was valid but there was some problem accessing it.IllegalStateException
- if called from the main thread.InterruptedException
public static boolean isKeyAlgorithmSupported(String algorithm)
true
if the current device's KeyChain
supports a
specific PrivateKey
type indicated by algorithm
(e.g.,
"RSA").@Deprecated public static boolean isBoundKeyAlgorithm(String algorithm)
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
}
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 X509Certificate toCertificate(byte[] bytes)
public static Collection<X509Certificate> toCertificates(byte[] bytes)
public static KeyChain.KeyChainConnection bind(Context context) throws InterruptedException
InterruptedException
public static KeyChain.KeyChainConnection bindAsUser(Context context, UserHandle user) throws InterruptedException
InterruptedException