Added in API level 36

KeyStoreManager

class KeyStoreManager
kotlin.Any
   ↳ android.security.keystore.KeyStoreManager

This class provides methods for interacting with keys stored within the Android Keystore.

Summary

Constants
static Int

When passed into getSupplementaryAttestationInfo, getSupplementaryAttestationInfo returns the DER-encoded structure corresponding to the `Modules` schema described in the KeyMint HAL's KeyCreationResult.
Public methods
MutableList<X509Certificate!>

Returns a List of X509Certificate instances representing the certificate chain for the key that was previously shared with the app under the provided id.
Key

Returns the key with the specified id that was previously shared with the app.
KeyPair

Returns a KeyPair containing the public and private key associated with the key that was previously shared with the app under the provided id.
ByteArray

Returns tag-specific data required to interpret a tag's attested value.
Long
grantKeyAccess(alias: String, uid: Int)

Grants access to the key owned by the calling app stored under the specified alias to another app on the device with the provided uid.
Unit
revokeKeyAccess(alias: String, uid: Int)

Revokes access to the key in the app's namespace stored under the specified alias that was previously granted to another app on the device with the provided uid.

Constants

MODULE_HASH

Added in API level 36
static val MODULE_HASH: Int

When passed into getSupplementaryAttestationInfo, getSupplementaryAttestationInfo returns the DER-encoded structure corresponding to the `Modules` schema described in the KeyMint HAL's KeyCreationResult.aidl. The SHA-256 hash of this encoded structure is what's included with the tag in attestations. To ensure the returned encoded structure is the one attested to, clients should verify its SHA-256 hash matches the one in the attestation. Note that the returned structure can vary between boots.

Value: -1879047468

Public methods

getGrantedCertificateChainFromId

Added in API level 36
fun getGrantedCertificateChainFromId(id: Long): MutableList<X509Certificate!>

Returns a List of X509Certificate instances representing the certificate chain for the key that was previously shared with the app under the provided id.

If a java.security.PrivateKey has not been granted to the caller with the specified id, then an UnrecoverableKeyException is thrown.

Parameters
id Long: the ID of the asymmetric key that was shared with the app
Return
MutableList<X509Certificate!> a List of X509Certificates with the certificate at index 0 corresponding to the private key shared with the app This value cannot be null.
Exceptions
java.security.UnrecoverableKeyException if the specified key cannot be recovered
android.security.keystore.KeyPermanentlyInvalidatedException if the specified key was authorized to only be used if the user has been authenticated and a change has been made to the users lockscreen or biometric enrollment that permanently invalidates the key

getGrantedKeyFromId

Added in API level 36
fun getGrantedKeyFromId(id: Long): Key

Returns the key with the specified id that was previously shared with the app.

This method can return instances of both javax.crypto.SecretKey and . If a key with the provide id has not been granted to the caller, then an UnrecoverableKeyException is thrown.

Parameters
id Long: the ID of the key that was shared with the app
Return
Key the Key that was shared with the app This value cannot be null.
Exceptions
java.security.UnrecoverableKeyException if the specified key cannot be recovered
android.security.keystore.KeyPermanentlyInvalidatedException if the specified key was authorized to only be used if the user has been authenticated and a change has been made to the users lockscreen or biometric enrollment that permanently invalidates the key

getGrantedKeyPairFromId

Added in API level 36
fun getGrantedKeyPairFromId(id: Long): KeyPair

Returns a KeyPair containing the public and private key associated with the key that was previously shared with the app under the provided id.

If a java.security.PrivateKey has not been granted to the caller with the specified id, then an UnrecoverableKeyException is thrown.

Parameters
id Long: the ID of the private key that was shared with the app
Return
KeyPair a KeyPair containing the public and private key shared with the app This value cannot be null.
Exceptions
java.security.UnrecoverableKeyException if the specified key cannot be recovered
android.security.keystore.KeyPermanentlyInvalidatedException if the specified key was authorized to only be used if the user has been authenticated and a change has been made to the users lockscreen or biometric enrollment that permanently invalidates the key

getSupplementaryAttestationInfo

Added in API level 36
fun getSupplementaryAttestationInfo(tag: Int): ByteArray

Returns tag-specific data required to interpret a tag's attested value. When performing key attestation, the obtained attestation certificate contains a list of tags and their corresponding attested values. For some tags, additional information about the attested value can be queried via this API. See individual tags for specifics.

Parameters
tag Int: tag for which info is being requested Value is android.security.keystore.KeyStoreManager#MODULE_HASH
Return
ByteArray tag-specific info This value cannot be null.
Exceptions
android.security.KeyStoreException if the requested info is not available

grantKeyAccess

Added in API level 36
fun grantKeyAccess(
    alias: String, 
    uid: Int
): Long

Grants access to the key owned by the calling app stored under the specified alias to another app on the device with the provided uid.

This method supports granting access to instances of both javax.crypto.SecretKey and java.security.PrivateKey. The resulting ID will persist across reboots and can be used by the grantee app for the life of the key or until access is revoked with revokeKeyAccess(java.lang.String,int).

If the provided alias does not correspond to a key in the Android KeyStore, then an UnrecoverableKeyException is thrown.

Parameters
alias String: the alias of the key to be granted to another app This value cannot be null.
uid Int: the uid of the app to which the key should be granted
Return
Long the ID of the granted key; this can be shared with the specified app, and that app can use getGrantedKeyFromId(long) to access the key
Exceptions
java.security.UnrecoverableKeyException if the specified key cannot be recovered
android.security.KeyStoreException if an error is encountered when attempting to grant access to the key

revokeKeyAccess

Added in API level 36
fun revokeKeyAccess(
    alias: String, 
    uid: Int
): Unit

Revokes access to the key in the app's namespace stored under the specified alias that was previously granted to another app on the device with the provided uid.

If the provided alias does not correspond to a key in the Android KeyStore, then an UnrecoverableKeyException is thrown.

Parameters
alias String: the alias of the key to be revoked from another app This value cannot be null.
uid Int: the uid of the app from which the key access should be revoked
Exceptions
java.security.UnrecoverableKeyException if the specified key cannot be recovered
android.security.KeyStoreException if an error is encountered when attempting to revoke access to the key