KeyChain

ACTION_KEYCHAIN_CHANGED

static val ACTION_KEYCHAIN_CHANGED: String

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

Value: "android.security.action.KEYCHAIN_CHANGED"

ACTION_KEY_ACCESS_CHANGED

static val ACTION_KEY_ACCESS_CHANGED: String

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

Value: "android.security.action.KEY_ACCESS_CHANGED"

ACTION_STORAGE_CHANGED

static val ACTION_STORAGE_CHANGED: String

Deprecated: Use ACTION_KEYCHAIN_CHANGED, ACTION_TRUST_STORE_CHANGED or ACTION_KEY_ACCESS_CHANGED. Apps that target a version higher than android.os.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.

Value: "android.security.STORAGE_CHANGED"

ACTION_TRUST_STORE_CHANGED

static val ACTION_TRUST_STORE_CHANGED: String

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

Value: "android.security.action.TRUST_STORE_CHANGED"

EXTRA_CERTIFICATE

static val EXTRA_CERTIFICATE: String

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.

Value: "CERT"

EXTRA_KEY_ACCESSIBLE

static val EXTRA_KEY_ACCESSIBLE: String

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

Value: "android.security.extra.KEY_ACCESSIBLE"

EXTRA_KEY_ALIAS

static val EXTRA_KEY_ALIAS: String

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

Value: "android.security.extra.KEY_ALIAS"

EXTRA_NAME

static val EXTRA_NAME: String

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

Value: "name"

EXTRA_PKCS12

static val EXTRA_PKCS12: String

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 java.security.KeyStore#store on a "PKCS12" instance.

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

The key store will be scanned for 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.

Value: "PKCS12"

KEY_ALIAS_SELECTION_DENIED

static val KEY_ALIAS_SELECTION_DENIED: String

Used by DPC or delegated app in android.app.admin.DeviceAdminReceiver#onChoosePrivateKeyAlias or android.app.admin.DelegatedAdminReceiver#onChoosePrivateKeyAlias to identify that the requesting app is not granted access to any key, and nor will the user be able to grant access manually.

Value: "android:alias-selection-denied"

choosePrivateKeyAlias

static fun choosePrivateKeyAlias(
    activity: Activity, 
    response: KeyChainAliasCallback, 
    keyTypes: Array<String!>?, 
    issuers: Array<Principal!>?, 
    uri: Uri?, 
    alias: String?
): Unit

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.

choosePrivateKeyAlias

static fun choosePrivateKeyAlias(
    activity: Activity, 
    response: KeyChainAliasCallback, 
    keyTypes: Array<String!>?, 
    issuers: Array<Principal!>?, 
    host: String?, 
    port: Int, 
    alias: String?
): Unit

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.

createInstallIntent

static fun createInstallIntent(): Intent

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 android.app.Activity#startActivityForResult, Activity.RESULT_OK will be returned if a credential was successfully installed, otherwise android.app.Activity#RESULT_CANCELED will be returned.

Starting from android.os.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 android.provider.MediaStore API to write the certificate to the android.provider.MediaStore.Downloads collection.

createManageCredentialsIntent

static fun createManageCredentialsIntent(policy: AppUriAuthenticationPolicy): Intent

Returns an Intent that should be used by an app to request to manage the user's credentials. This is limited to unmanaged devices. The authentication policy must be provided to be able to make this request successfully.

This intent should be started using Activity.startActivityForResult(Intent, int) to verify whether the request was successful and whether the user accepted or denied the request. If the user successfully receives and accepts the request, the result code will be Activity.RESULT_OK, otherwise the result code will be Activity.RESULT_CANCELED.

KeyChain.isCredentialManagementApp(Context) should be used to determine whether an app is already the credential management app.

getCertificateChain

static fun getCertificateChain(
    context: Context, 
    alias: String
): Array<X509Certificate!>?

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

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 again. See getPrivateKey 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.

getCredentialManagementAppPolicy

static fun getCredentialManagementAppPolicy(context: Context): AppUriAuthenticationPolicy

Called by the credential management app to get the authentication policy AppUriAuthenticationPolicy.
This method may take several seconds to complete, so it should only be called from a worker thread.

getPrivateKey

static fun getPrivateKey(
    context: Context, 
    alias: String
): PrivateKey?

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

isBoundKeyAlgorithm

static fun isBoundKeyAlgorithm(algorithm: String): Boolean

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

<code>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
  }</code>

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.

isCredentialManagementApp

static fun isCredentialManagementApp(context: Context): Boolean

Check whether the caller is the credential management app CredentialManagementApp. The credential management app has the ability to manage the user's KeyChain credentials on unmanaged devices.

KeyChain.createManageCredentialsIntent should be used by an app to request to become the credential management app. The user must approve this request before the app can manage the user's credentials. There can only be one credential management on the device.
This method may take several seconds to complete, so it should only be called from a worker thread.

isKeyAlgorithmSupported

static fun isKeyAlgorithmSupported(algorithm: String): Boolean

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

removeCredentialManagementApp

static fun removeCredentialManagementApp(context: Context): Boolean

Called by the credential management app CredentialManagementApp to unregister as the credential management app and stop managing the user's credentials.

All credentials previously installed by the credential management app will be removed from the user's device.

An app holding MANAGE_CREDENTIAL_MANAGEMENT_APP permission can also call this method to remove the current credential management app, even if it's not the current credential management app itself.
This method may take several seconds to complete, so it should only be called from a worker thread.