Verify hardware-backed key pairs with 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 attestation certificates' extension data.

Note: Before you verify the properties of a device's hardware-backed keys in a production-level environment, make sure that the device supports hardware-level key attestation. To do so, 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 or to the StrongBox security level.

In addition, it's important to verify the signatures in the certificate chain and to confirm that none of the keys in the chain have been revoked by checking the certificate revocation status list. Unless all are valid and the root is the Google root key, don'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.

Retrieve and verify a hardware-backed key pair

During key attestation, you specify the alias of a key pair and retrieve its 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 that is securely provisioned to the device's hardware-backed keystore.

Note: On devices that ship with hardware-level key attestation, Android 7.0 (API level 24) or higher, and Google Play services, the root certificate is signed with the Google attestation root key. Verify that this root certificate is among those listed in the section on root certificates.

To implement key attestation, complete the following steps:

Use a KeyStore object's getCertificateChain() method to get a reference to the chain of X.509 certificates associated with the hardware-backed keystore.
Send the certificates to a separate server that you trust for validation.

Caution: Don't complete the following validation process on the same device as the KeyStore. If the Android system on that device is compromised, that could cause the validation process to trust something that is untrustworthy.
Obtain a reference to the X.509 certificate chain parsing and validation library that is most appropriate for your toolset. Verify that the root public certificate is trustworthy and that each certificate signs the next certificate in the chain.
Check each certificate's revocation status to ensure that none of the certificates have been revoked.
Optionally, inspect the provisioning information certificate extension that is only present in newer certificate chains.

Obtain a reference to the CBOR parser library that is most appropriate for your toolset. Find the nearest certificate to the root that contains the provisioning information certificate extension. Use the parser to extract the provisioning information certificate extension data from that certificate.

See the section about the provisioning information extension data schema for more details.
Obtain a reference to the ASN.1 parser library that is most appropriate for your toolset. Find the nearest certificate to the root that contains the key attestation certificate extension. If the provisioning information certificate extension was present, the key attestation certificate extension must be in the immediately subsequent certificate. Use the parser to extract the key attestation certificate extension data from that certificate.

Caution: Do not assume that the key attestation certificate extension is in the leaf certificate of the chain. Only the first occurrence of the extension in the chain can be trusted. Any further instances of the extension have not been issued by the secure hardware and might have been issued by an attacker extending the chain while attempting to create fake attestations for untrusted keys.

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.

See the section about the key attestation extension data schema for more details.
Check the extension data that you've retrieved in the previous steps for consistency and compare with the set of values that you expect the hardware-backed key to contain.

Root certificates

The trustworthiness of the attestation depends on the root certificate of the chain. Android devices that have passed the testing required to have the Google suite of apps, including Google Play, and which launched with Android 7.0 (API level 24) or higher should use attestation keys signed by the Google Hardware Attestation Root certificate. Note that attestation was not required until Android 8.0 (API level 26). The root public key is as follows:

Previously Issued Root Certificates

If the root certificate in the attestation chain you receive contains this public key and none of the certificates in the chain have been revoked, you know that:

Your key is in hardware that Google believes to be secure; and
It has the properties described in the attestation certificate.

If the attestation chain has any other root public key, then Google does not make any claims about the security of the hardware. This doesn't mean that your key is compromised, only that the attestation doesn't prove that the key is in secure hardware. Adjust your security assumptions accordingly.

If the root certificate doesn't contain the public key on this page, there are two likely reasons:

Most likely, the device launched with an Android version less than 7.0 and it doesn't support hardware attestation. In this case, Android has a software implementation of attestation that produces the same sort of attestation certificate, but signed with a key hardcoded in Android source code. Because this signing key isn't a secret, the attestation might have been created by an attacker pretending to provide secure hardware.
The other likely reason is that the device isn't a Google Play device. In that case, the device maker is free to create their own root and to make whatever claims they like about what the attestation means. Refer to the device maker's documentation. Note that as of this writing Google isn't aware of any device makers who have done this.

Certificate revocation status list

Attestation keys can be revoked for a number of reasons, including mishandling or suspected extraction by an attacker. Therefore, it's critical that the status of each certificate in an attestation chain be checked against the official certificate revocation status list (CRL). This list is maintained by Google and published at: https://android.googleapis.com/attestation/status. The Cache-Control header in the HTTP response determines how often to check for updates so a network request is not required for every certificate being verified. This URL returns a JSON file containing the revocation status for any certificates that don't have a normal valid status. The format of the JSON file adheres to the following JSON Schema (draft 07) definition:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "entries": {
      "description" : "Each entry represents the status of an attestation key. The dictionary-key is the certificate serial number in lowercase hex.",
      "type": "object",
      "propertyNames": {
        "pattern": "^[a-f1-9][a-f0-9]*$"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "status": {
            "description": "[REQUIRED] Current status of the key.",
            "type": "string",
            "enum": ["REVOKED", "SUSPENDED"]
          },
          "expires": {
            "description": "[OPTIONAL] UTC date when certificate expires in ISO8601 format (YYYY-MM-DD). Can be used to clear expired certificates from the status list.",
            "type": "string",
            "format": "date"
          },
          "reason": {
            "description": "[OPTIONAL] Reason for the current status.",
            "type": "string",
            "enum": ["UNSPECIFIED", "KEY_COMPROMISE", "CA_COMPROMISE", "SUPERSEDED", "SOFTWARE_FLAW"]
          },
          "comment": {
            "description": "[OPTIONAL] Free form comment about the key status.",
            "type": "string",
            "maxLength": 140
          }
        },
        "required": ["status"],
        "additionalProperties": false
      }
    }
  },
  "required": ["entries"],
  "additionalProperties": false
}

Example CRL:

{
  "entries": {
    "2c8cdddfd5e03bfc": {
      "status": "REVOKED",
      "expires": "2020-11-13",
      "reason": "KEY_COMPROMISE",
      "comment": "Key stored on unsecure system"
    },
    "c8966fcb2fbb0d7a": {
      "status": "SUSPENDED",
      "reason": "SOFTWARE_FLAW",
      "comment": "Bug in keystore causes this key malfunction b/555555"
    }
  }
}

Key attestation extension data schema

The key attestation extension has OID 1.3.6.1.4.1.11129.2.1.17. The extension stores the information according to an ASN.1 schema.

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.

Value	Version
1	Keymaster version 2.0
2	Keymaster version 3.0
3	Keymaster version 4.0
4	Keymaster version 4.1
100	KeyMint version 1.0
200	KeyMint version 2.0
300	KeyMint version 3.0

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 can't trust these attestations if the Android system becomes compromised.

keymasterVersion / keyMintVersion

The version of the Keymaster or KeyMint hardware abstraction layer (HAL).

Value	Version
0	Keymaster version 0.2 or 0.3
1	Keymaster version 1.0
2	Keymaster version 2.0
3	Keymaster version 3.0
4	Keymaster version 4.0
41	Keymaster version 4.1
100	KeyMint version 1.0
200	KeyMint version 2.0
300	KeyMint version 3.0

keymasterSecurityLevel / keyMintSecurityLevel

The security level of the Keymaster/KeyMint implementation.

attestationChallenge

Contains the challenge that was provided at key creation time. Check whether this value matches the value your server provided, as stored in the Tag::ATTESTATION_CHALLENGE authorization tag. Otherwise, your service might be vulnerable to replaying of old attestation certificates.

uniqueId

This value identifies the device—but only for a limited period of time. It is computed and is only used by system apps. In all other apps, uniqueId is empty.

softwareEnforced

Optional. The Keymaster / KeyMint authorization list that is enforced by the Android system, not by the device's Trusted Execution Environment (TEE). Information in this authorization list is collected or generated by code that is part of the platform and is stored in the system partition of the device. The contents of this authorization list can be trusted as long as the device is running an operating system that is compliant with the Android Platform Security Model. All certified Android devices comply with this security model, so if the device is locked and the verified boot state is Verified, then the values here should be reliable. On a modified device, where the bootloader is unlocked, the user can install an operating system that is not compliant with the Android Platform Security Model, so the values in this field might be arbitrarily chosen by the user.

hardwareEnforced

Optional. The Keymaster / KeyMint authorization list that is enforced by the device's Trusted Execution Environment (TEE). Information in this authorization list is collected or generated by code that is a part of the secure hardware and is not controlled by the platform. For example, information in this authorization list comes from the device's bootloader or the TEE running on the device. Fields in this authorization list that are not directly set by KeyMint are provided by other parts of the secure hardware (for example, the bootloader) through secure communication channels that do not involve trusting the platform. The distinction between the secure hardware and the Android system is that the user cannot modify the code running in the secure hardware (the firmware) so the user cannot subvert the values in this authorization list.

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:

Keystore: 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.
StrongBox: The logic for creating and managing the feature is implemented in a dedicated hardware security module. For the purposes of creating and storing key pairs, this location is more secure because it is highly resistant to remote compromise and hardware attacks against the module.
Software: The logic for creating and managing the feature is implemented in a KeyMint or Keymaster implementation that does not run in a secure environment. 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.

AuthorizationList

This data structure contains the key pair's properties themselves, as defined in the Keymaster or KeyMint 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 / KeyMint authorization tag. For example, the keySize field in an authorization list corresponds to the Tag::KEY_SIZE authorization tag.

The AIDL interface specification holds the definitive information about authorization tags. This defines the ID value and type of each tag, and also indicates whether each tag is expected to be present in the hardwareEnforced authorization list (indicating that the tag is enforced in the secure environment), or in the softwareEnforced authorization list (indicating that the tag is enforced by Android, typically by Keystore).

Each field in the following list is optional:

purpose

Corresponds to the Tag::PURPOSE authorization tag, which uses a tag ID value of 1.

algorithm

Corresponds to the Tag::ALGORITHM authorization tag, which uses a tag ID value of 2.

In an attestation AuthorizationList object, the algorithm value is always RSA or EC.

keySize

Corresponds to the Tag::KEY_SIZE authorization tag, which uses a tag ID value of 3.

digest

Corresponds to the Tag::DIGEST authorization tag, which uses a tag ID value of 5.

padding

Corresponds to the Tag::PADDING authorization tag, which uses a tag ID value of 6.

ecCurve

Corresponds to the Tag::EC_CURVE authorization 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 Tag::RSA_PUBLIC_EXPONENT authorization tag, which uses a tag ID value of 200.

mgfDigest

Present only in key attestation version >= 100.

Corresponds to the Tag::RSA_OAEP_MGF_DIGEST KeyMint authorization tag, which uses a tag ID value of 203.

rollbackResistance

Present only in key attestation version >= 3.

Corresponds to the Tag::ROLLBACK_RESISTANT authorization tag, which uses a tag ID value of 303.

earlyBootOnly

Present only in key attestation version >= 4.

Corresponds to the Tag::EARLY_BOOT_ONLY authorization tag, which uses a tag ID value of 305.

activeDateTime

Corresponds to the Tag::ACTIVE_DATETIME authorization tag, which uses a tag ID value of 400.

originationExpireDateTime

Corresponds to the Tag::ORIGINATION_EXPIRE_DATETIME Keymaster authorization tag, which uses a tag ID value of 401.

usageExpireDateTime

Corresponds to the Tag::USAGE_EXPIRE_DATETIME authorization tag, which uses a tag ID value of 402.

usageCountLimit

Corresponds to the Tag::USAGE_COUNT_LIMIT authorization tag, which uses a tag ID value of 405.

noAuthRequired

Corresponds to the Tag::NO_AUTH_REQUIRED authorization tag, which uses a tag ID value of 503.

userAuthType

Corresponds to the Tag::USER_AUTH_TYPE authorization tag, which uses a tag ID value of 504.

authTimeout

Corresponds to the Tag::AUTH_TIMEOUT authorization tag, which uses a tag ID value of 505.

allowWhileOnBody

Corresponds to the Tag::ALLOW_WHILE_ON_BODY authorization 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.

trustedUserPresenceRequired

Present only in key attestation version >= 3.

Corresponds to the Tag::TRUSTED_USER_PRESENCE_REQUIRED authorization tag, which uses a tag ID value of 507.

Specifies that this key is usable only if the user has provided proof of physical presence. Several examples include the following:

For a StrongBox key, a hardware button hardwired to a pin on the StrongBox device.
For a TEE key, fingerprint authentication provides proof of presence as long as the TEE has exclusive control of the scanner and performs the fingerprint matching process.

trustedConfirmationRequired

Present only in key attestation version >= 3.

Corresponds to the Tag::TRUSTED_CONFIRMATION_REQUIRED authorization tag, which uses a tag ID value of 508.

Specifies that the key is usable only if the user provides confirmation of the data to be signed using an approval token. For more information about how to obtain user confirmation, see Android Protected Confirmation.

Note: This tag is only applicable to keys that use the SIGN purpose.

unlockedDeviceRequired

Present only in key attestation version >= 3.

Corresponds to the Tag::UNLOCKED_DEVICE_REQUIRED authorization tag, which uses a tag ID value of 509.

allApplications

Corresponds to the Tag::ALL_APPLICATIONS authorization 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 Tag::APPLICATION_ID authorization tag, which uses a tag ID value of 601.

creationDateTime

Corresponds to the Tag::CREATION_DATETIME authorization tag, which uses a tag ID value of 701.

origin

Corresponds to the Tag::ORIGIN authorization tag, which uses a tag ID value of 702.

rollbackResistant

Present only in key attestation versions 1 and 2.

Corresponds to the Tag::ROLLBACK_RESISTANT authorization tag, which uses a tag ID value of 703.

rootOfTrust

Corresponds to the Tag::ROOT_OF_TRUST authorization tag, which uses a tag ID value of 704.

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

osVersion

Corresponds to the Tag::OS_VERSION authorization 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 8.1.0 is represented as 080100.

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

osPatchLevel

Corresponds to the Tag::PATCHLEVEL authorization 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 August 2018 patch is represented as 201808.

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

attestationApplicationId