Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.
added in API level 23

KeyInfo

public class KeyInfo
extends Object implements KeySpec

java.lang.Object
   ↳ android.security.keystore.KeyInfo


Information about a key from the Android Keystore system. This class describes whether the key material is available in plaintext outside of secure hardware, whether user authentication is required for using the key and whether this requirement is enforced by secure hardware, the key's origin, what uses the key is authorized for (e.g., only in GCM mode, or signing only), whether the key should be encrypted at rest, the key's and validity start and end dates.

Instances of this class are immutable.

Example: Symmetric Key

The following example illustrates how to obtain a KeyInfo describing the provided Android Keystore SecretKey.
SecretKey key = ...; // Android Keystore key

 SecretKeyFactory factory = SecretKeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
 KeyInfo keyInfo;
 try {
     keyInfo = (KeyInfo) factory.getKeySpec(key, KeyInfo.class);
 } catch (InvalidKeySpecException e) {
     // Not an Android KeyStore key.
 }

Example: Private Key

The following example illustrates how to obtain a KeyInfo describing the provided Android KeyStore PrivateKey.
PrivateKey key = ...; // Android KeyStore key

 KeyFactory factory = KeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
 KeyInfo keyInfo;
 try {
     keyInfo = factory.getKeySpec(key, KeyInfo.class);
 } catch (InvalidKeySpecException e) {
     // Not an Android KeyStore key.
 }

Summary

Public methods

String[] getBlockModes()

Gets the set of block modes (e.g., GCM, CBC) with which the key can be used when encrypting/decrypting.

String[] getDigests()

Gets the set of digest algorithms (e.g., SHA-256, SHA-384) with which the key can be used.

String[] getEncryptionPaddings()

Gets the set of padding schemes (e.g., PKCS7Padding, PKCS1Padding, NoPadding) with which the key can be used when encrypting/decrypting.

int getKeySize()

Gets the size of the key in bits.

Date getKeyValidityForConsumptionEnd()

Gets the time instant after which the key is no long valid for decryption and verification.

Date getKeyValidityForOriginationEnd()

Gets the time instant after which the key is no long valid for encryption and signing.

Date getKeyValidityStart()

Gets the time instant before which the key is not yet valid.

String getKeystoreAlias()

Gets the entry alias under which the key is stored in the AndroidKeyStore.

int getOrigin()

Gets the origin of the key.

int getPurposes()

Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used.

String[] getSignaturePaddings()

Gets the set of padding schemes (e.g., PSS, PKCS#1) with which the key can be used when signing/verifying.

int getUserAuthenticationValidityDurationSeconds()

Gets the duration of time (seconds) for which this key is authorized to be used after the user is successfully authenticated.

boolean isInsideSecureHardware()

Returns true if the key resides inside secure hardware (e.g., Trusted Execution Environment (TEE) or Secure Element (SE)).

boolean isInvalidatedByBiometricEnrollment()

Returns true if the key will be invalidated by enrollment of a new fingerprint or removal of all fingerprints.

boolean isTrustedUserPresenceRequired()

Returns true if the key can only be only be used if a test for user presence has succeeded since Signature.initSign() has been called.

boolean isUserAuthenticationRequired()

Returns true if the key is authorized to be used only if the user has been authenticated.

boolean isUserAuthenticationRequirementEnforcedBySecureHardware()

Returns true if the requirement that this key can only be used if the user has been authenticated is enforced by secure hardware (e.g., Trusted Execution Environment (TEE) or Secure Element (SE)).

boolean isUserAuthenticationValidWhileOnBody()

Returns true if this key will become unusable when the device is removed from the user's body.

boolean isUserConfirmationRequired()

Returns true if the key is authorized to be used only for messages confirmed by the user.

Inherited methods

Public methods

getBlockModes

added in API level 23
public String[] getBlockModes ()

Gets the set of block modes (e.g., GCM, CBC) with which the key can be used when encrypting/decrypting. Attempts to use the key with any other block modes will be rejected.

See KeyProperties.BLOCK_MODE constants.

Returns
String[]

This value will never be null.

Value is BLOCK_MODE_ECB, BLOCK_MODE_CBC, BLOCK_MODE_CTR or BLOCK_MODE_GCM.

getDigests

added in API level 23
public String[] getDigests ()

Gets the set of digest algorithms (e.g., SHA-256, SHA-384) with which the key can be used.

See KeyProperties.DIGEST constants.

Returns
String[]

This value will never be null.

Value is DIGEST_NONE, DIGEST_MD5, DIGEST_SHA1, DIGEST_SHA224, DIGEST_SHA256, DIGEST_SHA384 or DIGEST_SHA512.

getEncryptionPaddings

added in API level 23
public String[] getEncryptionPaddings ()

Gets the set of padding schemes (e.g., PKCS7Padding, PKCS1Padding, NoPadding) with which the key can be used when encrypting/decrypting. Attempts to use the key with any other padding scheme will be rejected.

See KeyProperties.ENCRYPTION_PADDING constants.

Returns
String[]

This value will never be null.

Value is ENCRYPTION_PADDING_NONE, ENCRYPTION_PADDING_PKCS7, ENCRYPTION_PADDING_RSA_PKCS1 or ENCRYPTION_PADDING_RSA_OAEP.

getKeySize

added in API level 23
public int getKeySize ()

Gets the size of the key in bits.

Returns
int

getKeyValidityForConsumptionEnd

added in API level 23
public Date getKeyValidityForConsumptionEnd ()

Gets the time instant after which the key is no long valid for decryption and verification.

Returns
Date instant or null if not restricted.

getKeyValidityForOriginationEnd

added in API level 23
public Date getKeyValidityForOriginationEnd ()

Gets the time instant after which the key is no long valid for encryption and signing.

Returns
Date instant or null if not restricted.

getKeyValidityStart

added in API level 23
public Date getKeyValidityStart ()

Gets the time instant before which the key is not yet valid.

Returns
Date instant or null if not restricted.

getKeystoreAlias

added in API level 23
public String getKeystoreAlias ()

Gets the entry alias under which the key is stored in the AndroidKeyStore.

Returns
String

getOrigin

added in API level 23
public int getOrigin ()

Gets the origin of the key. See KeyProperties.ORIGIN constants.

Returns
int

Value is ORIGIN_GENERATED, ORIGIN_IMPORTED or ORIGIN_UNKNOWN.

getPurposes

added in API level 23
public int getPurposes ()

Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used. Attempts to use the key for any other purpose will be rejected.

See KeyProperties.PURPOSE flags.

Returns
int

Value is either 0 or combination of PURPOSE_ENCRYPT, PURPOSE_DECRYPT, PURPOSE_SIGN, PURPOSE_VERIFY or PURPOSE_WRAP_KEY.

getSignaturePaddings

added in API level 23
public String[] getSignaturePaddings ()

Gets the set of padding schemes (e.g., PSS, PKCS#1) with which the key can be used when signing/verifying. Attempts to use the key with any other padding scheme will be rejected.

See KeyProperties.SIGNATURE_PADDING constants.

Returns
String[]

This value will never be null.

Value is SIGNATURE_PADDING_RSA_PKCS1 or SIGNATURE_PADDING_RSA_PSS.

getUserAuthenticationValidityDurationSeconds

added in API level 23
public int getUserAuthenticationValidityDurationSeconds ()

Gets the duration of time (seconds) for which this key is authorized to be used after the user is successfully authenticated. This has effect only if user authentication is required (see isUserAuthenticationRequired()).

This authorization applies only to secret key and private key operations. Public key operations are not restricted.

Returns
int duration in seconds or -1 if authentication is required for every use of the key.

isInsideSecureHardware

added in API level 23
public boolean isInsideSecureHardware ()

Returns true if the key resides inside secure hardware (e.g., Trusted Execution Environment (TEE) or Secure Element (SE)). Key material of such keys is available in plaintext only inside the secure hardware and is not exposed outside of it.

Returns
boolean

isInvalidatedByBiometricEnrollment

added in API level 24
public boolean isInvalidatedByBiometricEnrollment ()

Returns true if the key will be invalidated by enrollment of a new fingerprint or removal of all fingerprints.

Returns
boolean

isTrustedUserPresenceRequired

added in API level 28
public boolean isTrustedUserPresenceRequired ()

Returns true if the key can only be only be used if a test for user presence has succeeded since Signature.initSign() has been called.

Returns
boolean

isUserAuthenticationRequired

added in API level 23
public boolean isUserAuthenticationRequired ()

Returns true if the key is authorized to be used only if the user has been authenticated.

This authorization applies only to secret key and private key operations. Public key operations are not restricted.

Returns
boolean

isUserAuthenticationRequirementEnforcedBySecureHardware

added in API level 23
public boolean isUserAuthenticationRequirementEnforcedBySecureHardware ()

Returns true if the requirement that this key can only be used if the user has been authenticated is enforced by secure hardware (e.g., Trusted Execution Environment (TEE) or Secure Element (SE)).

Returns
boolean

isUserAuthenticationValidWhileOnBody

added in API level 24
public boolean isUserAuthenticationValidWhileOnBody ()

Returns true if this key will become unusable when the device is removed from the user's body. This is possible only for keys with a specified validity duration, and only on devices with an on-body sensor. Always returns false on devices that lack an on-body sensor.

Returns
boolean

isUserConfirmationRequired

added in API level 28
public boolean isUserConfirmationRequired ()

Returns true if the key is authorized to be used only for messages confirmed by the user. Confirmation is separate from user authentication (see isUserAuthenticationRequired()). Keys can be created that require confirmation but not user authentication, or user authentication but not confirmation, or both. Confirmation verifies that some user with physical possession of the device has approved a displayed message. User authentication verifies that the correct user is present and has authenticated.

This authorization applies only to secret key and private key operations. Public key operations are not restricted.

Returns
boolean