Skip to content

Most visited

Recently visited

navigation

Key Attestation

Key Attestation gives you more confidence that the keys you use in your app are stored in a device's hardware-backed keystore. The following sections describe how to verify the properties of hardware-backed keys and how to interpret the schema of the attestation certificate's extension data.

Note: Only a small number of devices running Android 7.0 (API level 24) support hardware-level key attestation; all other devices running Android 7.0 use software-level key attestation instead. Before you verify the properties of a device's hardware-backed keys in a production-level environment, you should make sure that the device supports hardware-level key attestation. To do so, you should check that the attestation certificate chain contains a root certificate that is signed with the Google attestation root key and that the attestationSecurityLevel element within the key description data structure is set to the TrustedEnvironment security level.

In addition, it's important to verify the signatures in the certificate chain and to check that none of the keys in the chain have been revoked by checking the Certificate Revocation List endpoint listed in each certificate. Unless all are valid and the root is the Google root key mentioned above, you shouldn't fully trust the attestation. Note, however, that devices containing revoked certificates are still at least as trustworthy as devices that only support software attestation. Having a fully-valid attestation is a strong positive indicator. Not having one is a neutral—not negative—indicator.

Retrieving and Verifying a Hardware-backed Key Pair

During key attestation, you specify the alias of a key pair. The attestation tool, in return, provides a certificate chain, which you can use to verify the properties of that key pair.

If the device supports hardware-level key attestation, the root certificate within this chain is signed using an attestation root key, which the device manufacturer injects into the device's hardware-backed keystore at the factory.

Note: On devices that ship with hardware-level key attestation, Android 7.0 (API level 24), and Google Play services, the root certificate is signed with the Google attestation root key. You should verify that this root certificate appears within Google's list of root certificates.

To implement key attestation, complete the following steps:

  1. Use a KeyStore object's getCertificateChain() method to get a reference to the chain of X.509 certificates associated with the hardware-backed keystore.
  2. Check each certificate's validity using a X509Certificate object's checkValidity() method.

    Caution: Although you can complete this process within your app directly, it's safer to check the certificates' revocation lists on a separate server that you trust.

  3. On a separate server that you trust, obtain a reference to the ASN.1 parser library that is most appropriate for your toolset. Use this parser to extract the attestation certificate extension data, which appears within the first element of the certificate chain.

    The Key Attestation sample uses the ASN.1 parser from Bouncy Castle to extract an attestation certificate's extension data. You can use this sample as a reference for creating your own parser.

    For more details about the schema of the extension data, see Certificate Extension Data Schema.

  4. Compare the extension data that you've retrieved from your ASN.1 parser with the set of values that you expect the hardware-backed key to contain.

    Caution: Although you can complete this process within your app directly, it's safer to check the certificate's extension data on a separate server that you trust.

Certificate Extension Data Schema

Key attestation verifies the extension data that appears in the first certificate within the chain in a device's hardware-backed keystore. The certificate stores the information according to the following ASN.1 schema:

KeyDescription ::= SEQUENCE {
    attestationVersion  INTEGER,
    attestationSecurityLevel  SecurityLevel,
    keymasterVersion  INTEGER,
    keymasterSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    reserved  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    teeEnforced  AuthorizationList,
}

SecurityLevel ::= ENUMERATED {
    Software  (0),
    TrustedEnvironment  (1),
}

AuthorizationList ::= SEQUENCE {
    purpose  [1] EXPLICIT SET OF INTEGER OPTIONAL,
    algorithm  [2] EXPLICIT INTEGER OPTIONAL,
    keySize  [3] EXPLICIT INTEGER OPTIONAL,
    digest  [5] EXPLICIT SET OF INTEGER OPTIONAL,
    padding  [6] EXPLICIT SET OF INTEGER OPTIONAL,
    ecCurve  [10] EXPLICIT INTEGER OPTIONAL,
    rsaPublicExponent  [200] EXPLICIT INTEGER OPTIONAL,
    activeDateTime  [400] EXPLICIT INTEGER OPTIONAL,
    originationExpireDateTime  [401] EXPLICIT INTEGER OPTIONAL,
    usageExpireDateTime  [402] EXPLICIT INTEGER OPTIONAL,
    noAuthRequired  [503] EXPLICIT NULL OPTIONAL,
    userAuthType  [504] EXPLICIT INTEGER OPTIONAL,
    authTimeout  [505] EXPLICIT INTEGER OPTIONAL,
    allowWhileOnBody  [506] EXPLICIT NULL OPTIONAL,
    allApplications  [600] EXPLICIT NULL OPTIONAL,
    applicationId  [601] EXPLICIT OCTET_STRING OPTIONAL,
    creationDateTime  [701] EXPLICIT INTEGER OPTIONAL,
    origin  [702] EXPLICIT INTEGER OPTIONAL,
    rollbackResistant  [703] EXPLICIT NULL OPTIONAL,
    rootOfTrust  [704] EXPLICIT RootOfTrust OPTIONAL,
    osVersion  [705] EXPLICIT INTEGER OPTIONAL,
    osPatchLevel  [706] EXPLICIT INTEGER OPTIONAL,
    attestationChallenge  [708] EXPLICIT INTEGER OPTIONAL,
    attestationApplicationId  [709] EXPLICIT OCTET_STRING OPTIONAL,
}

RootOfTrust ::= SEQUENCE {
    verifiedBootKey  OCTET_STRING,
    deviceLocked  BOOLEAN,
    verifiedBootState  VerifiedBootState,
}

VerifiedBootState ::= ENUMERATED {
    Verified  (0),
    SelfSigned  (1),
    Unverified  (2),
    Failed  (3),
}

The following list presents a description of each element within the schema:

KeyDescription

This sequence of values presents general information about the key pair being verified through key attestation and provides easy access to additional details.

attestationVersion
The version of the key attestation feature. Should be set to 1.
attestationSecurityLevel

The security level of the attestation.

Warning: Although it is possible to attest keys that are stored in the Android system—that is, if the value of attestationSecurityLevel is set to Software—you cannot trust these attestations if the Android system becomes compromised.

keymasterVersion
The version of the Keymaster hardware abstraction layer (HAL). Use 0 to represent version 0.2 or 0.3, 1 to represent version 1.0, and 2 to represent version 2.0.
keymasterSecurityLevel
The security level of the Keymaster implementation.
attestationChallenge
The challenge string associated with a key pair that is verified using key attestation.
reserved
Only system apps use this value. In all other apps, this value is empty.
softwareEnforced
Optional. The Keymaster authorization list that is enforced by the Android system, not by the device's TEE.
teeEnforced
Optional. The Keymaster authorization list that is enforced by the device's TEE.

SecurityLevel

This data structure indicates the extent to which a software feature, such as a key pair, is protected based on its location within the device.

Because the data structure is an enumeration, it takes on exactly one of the following values:

Software
The logic for creating and managing the feature is implemented in the Android system. For the purposes of creating and storing key pairs, this location is less secure than the TEE but is more secure than your app's process space.
TrustedEnvironment
The logic for creating and managing the feature is implemented in secure hardware, such as a TEE. For the purposes of creating and storing key pairs, this location is more secure because secure hardware is highly resistant to remote compromise.

AuthorizationList

This data structure contains the key pair's properties themselves, as defined in the Keymaster hardware abstraction layer (HAL). You compare these values to the device's current state or to a set of expected values to verify that a key pair is still valid for use in your app.

Each field name corresponds to a similarly-named Keymaster tag. For example, the keySize field in an authorization list corresponds to the KM_TAG_KEY_SIZE Keymaster tag.

Each field in the following list is optional:

purpose
Corresponds to the KM_TAG_PURPOSE Keymaster tag, which uses a tag ID value of 1.
algorithm

Corresponds to the KM_TAG_ALGORITHM Keymaster tag, which uses a tag ID value of 2.

In an attestation AuthorizationList object this value is always KM_ALGORITHM_RSA or KM_ALGORITHM_EC.

keySize
Corresponds to the KM_TAG_KEY_SIZE Keymaster tag, which uses a tag ID value of 3.
digest
Corresponds to the KM_TAG_DIGEST Keymaster tag, which uses a tag ID value of 5.
padding
Corresponds to the KM_TAG_PADDING Keymaster tag, which uses a tag ID value of 6.
ecCurve

Corresponds to the KM_TAG_EC_CURVE Keymaster tag, which uses a tag ID value of 10.

The set of parameters used to generate an elliptic curve (EC) key pair, which uses ECDSA for signing and verification, within the Android system keystore.

rsaPublicExponent
Corresponds to the KM_TAG_RSA_PUBLIC_EXPONENT Keymaster tag, which uses a tag ID value of 200.
activeDateTime
Corresponds to the KM_TAG_ACTIVE_DATETIME Keymaster tag, which uses a tag ID value of 400.
originationExpireDateTime
Corresponds to the KM_TAG_ORIGINATION_EXPIRE_DATETIME Keymaster tag, which uses a tag ID value of 401.
usageExpireDateTime
Corresponds to the KM_TAG_USAGE_EXPIRE_DATETIME Keymaster tag, which uses a tag ID value of 402.
noAuthRequired

Corresponds to the KM_TAG_NO_AUTH_REQUIRED Keymaster tag, which uses a tag ID value of 503.

userAuthType
Corresponds to the KM_TAG_USER_AUTH_TYPE Keymaster tag, which uses a tag ID value of 504.
authTimeout
Corresponds to the KM_TAG_AUTH_TIMEOUT Keymaster tag, which uses a tag ID value of 505.
allowWhileOnBody

Corresponds to the KM_TAG_ALLOW_WHILE_ON_BODY Keymaster tag, which uses a tag ID value of 506.

Allows the key to be used after its authentication timeout period if the user is still wearing the device on their body. Note that a secure on-body sensor determines whether the device is being worn on the user's body.

allApplications

Corresponds to the KM_TAG_ALL_APPLICATIONS Keymaster tag, which uses a tag ID value of 600.

Indicates whether all apps on a device can access the key pair.

applicationId
Corresponds to the KM_TAG_APPLICATION_ID Keymaster tag, which uses a tag ID value of 601.
creationDateTime
Corresponds to the KM_TAG_CREATION_DATETIME Keymaster tag, which uses a tag ID value of 701.
origin

Corresponds to the KM_TAG_ORIGIN Keymaster tag, which uses a tag ID value of 702.

rollbackResistant
Corresponds to the KM_TAG_ROLLBACK_RESISTANT Keymaster tag, which uses a tag ID value of 703.
rootOfTrust

Corresponds to the KM_TAG_ROOT_OF_TRUST Keymaster tag, which uses a tag ID value of 704.

For more details, see the section describing the RootOfTrust data structure.

osVersion

Corresponds to the KM_TAG_OS_VERSION Keymaster tag, which uses a tag ID value of 705.

The version of the Android operating system associated with the Keymaster, specified as a six-digit integer. For example, version 6.0.1 is represented as 060001.

Only Keymaster version 1.0 or higher includes this value in the authorization list.

osPatchLevel

Corresponds to the KM_TAG_PATCHLEVEL Keymaster tag, which uses a tag ID value of 706.

The month and year associated with the security patch that is being used within the Keymaster, specified as a six-digit integer. For example, the June 2016 patch is represented as 201606.

Only Keymaster version 1.0 or higher includes this value in the authorization list.

attestationChallenge

Corresponds to the KM_TAG_ATTESTATION_CHALLENGE Keymaster tag, which uses a tag ID value of 708.

The challenge string associated with the key pair that is defined in the Keymaster.

attestationApplicationId

Corresponds to the KM_TAG_ATTESTATION_APPLICATION_ID Keymaster tag, which uses a tag ID value of 709.

For more details, see the section describing the AttestationApplicationId data structure.

RootOfTrust

This collection of values defines key information about the device's status.

Each field in the following list is required:

verifiedBootKey

A secure hash of the key that verifies the system image. It is recommended that you use the SHA-256 algorithm for this hash.

deviceLocked
True if the device's bootloader is locked, which enables Verified Boot checking and prevents an unsigned device image from being flashed onto the device. For more information about this feature, see the Verifying Boot documentation.
verifiedBootState
The boot state of the device, according to the Verified Boot feature.
osVersion
The current version of the Android operating system on the device, specified as a six-digit integer. For example, version 6.0.1 is represented as 060001.
patchMonthYear
The month and year associated with the security patch that is currently installed on the device, specified as a six-digit integer. For example, the August 2016 patch is represented as 201608.

VerifiedBootState

This data structure provides the device's current boot state, which represents the level of protection provided to the user and to apps after the device finishes booting. For more information about this feature, see the Boot State section within the Verifying Boot documentation.

This data structure is an enumeration, so it takes on exactly one of the following values:

Verified

Indicates a full chain of trust, which includes the bootloader, the boot partition, and all verified partitions.

When the device is in this boot state, the verifiedBootKey is the hash of the device-embedded certificate, which the device manufacturer adds to the device's ROM at the factory.

SelfSigned

Indicates that the device-embedded certificate has verified the device's boot partition and that the signature is valid.

When the device is in this boot state, the verifiedBootKey is the hash of a user-installed certificate, which signs a boot partition that the user adds to the device in place of the original, manufacturer-provided boot partition.

Unverified
Indicates that the user can modify the device freely. Therefore, the user is responsible for verifying the device's integrity.
Failed
Indicates that the device has failed verification. The attestation certificate should never use this value for VerifiedBootState.

AttestationApplicationId

This data structure reflects the Android platform's belief as to which apps are allowed to use the secret key material under attestation. The ID can comprise multiple packages if and only if multiple packages share the same UID. The octet string is itself formatted according to the following ASN.1 schema:

AttestationApplicationId ::= SEQUENCE {
    package_infos  SET OF AttestationPackageInfo,
    signature_digests  SET OF OCTET_STRING,
}

AttestationPackageInfo ::= SEQUENCE {
    package_name  OCTET_STRING,
    version  INTEGER,
}
package_infos
A set of AttestationPackageInfo objects, each providing a package's name and version number.
signature_digests

A set of SHA-256 digests of the app's signature blobs, as contained within the signatures field of the PackageInfo that is returned upon a call to getPackageInfo(). The following code snippet shows an example set:

{SHA256(PackageInfo.signature[0]), SHA256(PackageInfo.signature[1]), ...}
This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)