Key and ID attestation

Keystore provides a more secure place to create, store, and use cryptographic keys in a controlled way. When hardware-backed key storage is available and used, key material is more secure against extraction from the device, and Keymaster enforces restrictions that are difficult to subvert.

This is only true, however, if the keystore keys are known to be in hardware-backed storage. In Keymaster 1, there was no way for apps or remote servers to reliably verify if this was the case. The keystore daemon loaded the available keymaster HAL and believed whatever the HAL said with respect to hardware backing of keys.

To remedy this, Keymaster introduced key attestation in Android 7.0 (Keymaster 2) and ID attestation in Android 8.0 (Keymaster 3).

Key attestation aims to provide a way to strongly determine if an asymmetric key pair is hardware-backed, what the properties of the key are, and what constraints are applied to its usage.

ID attestation allows the device to provide proof of its hardware identifiers, such as serial number or IMEI.

Note: To support Keymaster 3's transition from the old-style C-structure HAL to the C++ HAL interface generated from a definition in the new Hardware Interface Definition Language (HIDL), tag and method names have changed in Android 8.0. Tags, like all other keymaster enums, are now defined as C++ scoped enums. For example, tags, formerly prefixed with KM_TAG_, are now prefixed with Tag:: and methods are in camel case. The examples below use Keymaster 3 terms, unless specified otherwise.

Key attestation

To support key attestation, Android 7.0 introduced a set of tags, type, and method to the HAL.

Tags

• Tag::ATTESTATION_CHALLENGE
• Tag::INCLUDE_UNIQUE_ID
• Tag::RESET_SINCE_ID_ROTATION

Type

Keymaster 2 and below

typedef struct {
    keymaster_blob_t* entries;
    size_t entry_count;
} keymaster_cert_chain_t;

AttestKey method

Keymaster 3

    attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams)
        generates(ErrorCode error, vec<vec<uint8_t>> certChain);

Keymaster 2 and below

keymaster_error_t (*attest_key)(const struct keymaster2_device* dev,
        const keymaster_key_blob_t* key_to_attest,
        const keymaster_key_param_set_t* attest_params,
        keymaster_cert_chain_t* cert_chain);

• dev is the keymaster device structure.
• keyToAttest is the key blob returned from generateKey for which the attestation is created.
• attestParams is a list of any parameters necessary for attestation. This includes Tag::ATTESTATION_CHALLENGE and possibly Tag::RESET_SINCE_ID_ROTATION, as well as Tag::APPLICATION_ID and Tag::APPLICATION_DATA. The latter two are necessary to decrypt the key blob if they were specified during key generation.
• certChain is the output parameter, which returns an array of certificates. Entry 0 is the attestation certificate, meaning it certifies the key from keyToAttest and contains the attestation extension.

The attestKey method is considered a public key operation on the attested key, because it can be called at any time and doesn't need to meet authorization constraints. For example, if the attested key needs user authentication for use, an attestation can be generated without user authentication.

Attestation certificate

The attestation certificate is a standard X.509 certificate, with an optional attestation extension that contains a description of the attested key. The certificate is signed with a certified attestation key. The attestation key might use a different algorithm than the key being attested.

The attestation certificate contains the fields in the table below and can't contain any additional fields. Some fields specify a fixed field value. CTS tests validate that the certificate content is exactly as defined.

Certificate SEQUENCE

Field name (see RFC 5280)	Value
tbsCertificate	TBSCertificate SEQUENCE
signatureAlgorithm	AlgorithmIdentifier of algorithm used to sign key: ECDSA for EC keys, RSA for RSA keys.
signatureValue	BIT STRING, signature computed on ASN.1 DER-encoded tbsCertificate.

TBSCertificate SEQUENCE

Field name (see RFC 5280)	Value
version	INTEGER 2 (means v3 certificate)
serialNumber	INTEGER 1 (fixed value: same on all certs)
signature	AlgorithmIdentifier of algorithm used to sign key: ECDSA for EC keys, RSA for RSA keys.
issuer	Same as the subject field of the batch attestation key.
validity	SEQUENCE of two dates, containing the values of Tag::ACTIVE_DATETIME and Tag::USAGE_EXPIRE_DATETIME. Those values are in milliseconds since Jan 1, 1970. See RFC 5280 for correct date representations in certificates. If Tag::ACTIVE_DATETIME is not present, use the value of Tag::CREATION_DATETIME. If Tag::USAGE_EXPIRE_DATETIME is not present, use the expiration date of the batch attestation key certificate.
subject	CN = "Android Keystore Key" (fixed value: same on all certs)
subjectPublicKeyInfo	SubjectPublicKeyInfo containing attested public key.
extensions/Key Usage	digitalSignature: set if key has purpose KeyPurpose::SIGN or KeyPurpose::VERIFY. All other bits unset.
extensions/CRL Distribution Points	Value TBD
extensions/"attestation"	The OID is 1.3.6.1.4.1.11129.2.1.17; the content is defined in the Attestation extension section below. As with all X.509 certificate extensions, the content is represented as an OCTET_STRING containing a DER encoding of the attestation SEQUENCE.

Attestation extension

The attestation extension has OID 1.3.6.1.4.1.11129.2.1.17. It contains information about the key pair being attested and the state of the device at key generation time.

The Keymaster/KeyMint tag types defined in the AIDL interface specification are translated to ASN.1 types as follows:

Keymaster/KeyMint type	ASN.1 type	Notes
ENUM	INTEGER
ENUM_REP	SET of INTEGER
UINT	INTEGER
UINT_REP	SET of INTEGER
ULONG	INTEGER
ULONG_REP	SET of INTEGER
DATE	INTEGER	Milliseconds since Jan 1, 1970 00:00:00 GMT.
BOOL	NULL	Tag presence means true, absence means false.
BIGNUM		No tags have this type, so no mapping is defined.
BYTES	OCTET_STRING

Schema

The attestation extension content is described by the following ASN.1 schema:

Version 300

KeyDescription ::= SEQUENCE {
    attestationVersion  300,
    attestationSecurityLevel  SecurityLevel,
    keyMintVersion  INTEGER,
    keyMintSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    uniqueId  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    hardwareEnforced  AuthorizationList,
}

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

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,
    mgfDigest  [203] EXPLICIT SET OF INTEGER OPTIONAL,
    rollbackResistance  [303] EXPLICIT NULL OPTIONAL,
    earlyBootOnly  [305] EXPLICIT NULL OPTIONAL,
    activeDateTime  [400] EXPLICIT INTEGER OPTIONAL,
    originationExpireDateTime  [401] EXPLICIT INTEGER OPTIONAL,
    usageExpireDateTime  [402] EXPLICIT INTEGER OPTIONAL,
    usageCountLimit  [405] EXPLICIT INTEGER OPTIONAL,
    noAuthRequired  [503] EXPLICIT NULL OPTIONAL,
    userAuthType  [504] EXPLICIT INTEGER OPTIONAL,
    authTimeout  [505] EXPLICIT INTEGER OPTIONAL,
    allowWhileOnBody  [506] EXPLICIT NULL OPTIONAL,
    trustedUserPresenceRequired  [507] EXPLICIT NULL OPTIONAL,
    trustedConfirmationRequired  [508] EXPLICIT NULL OPTIONAL,
    unlockedDeviceRequired  [509] EXPLICIT NULL OPTIONAL,
    creationDateTime  [701] EXPLICIT INTEGER OPTIONAL,
    origin  [702] EXPLICIT INTEGER OPTIONAL,
    rootOfTrust  [704] EXPLICIT RootOfTrust OPTIONAL,
    osVersion  [705] EXPLICIT INTEGER OPTIONAL,
    osPatchLevel  [706] EXPLICIT INTEGER OPTIONAL,
    attestationApplicationId  [709] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdBrand  [710] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdDevice  [711] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdProduct  [712] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdSerial  [713] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdImei  [714] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdMeid  [715] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdManufacturer  [716] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdModel  [717] EXPLICIT OCTET_STRING OPTIONAL,
    vendorPatchLevel  [718] EXPLICIT INTEGER OPTIONAL,
    bootPatchLevel  [719] EXPLICIT INTEGER OPTIONAL,
    deviceUniqueAttestation  [720] EXPLICIT NULL OPTIONAL,
    attestationIdSecondImei  [723] EXPLICIT OCTET_STRING OPTIONAL,
}

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

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

Version 200

KeyDescription ::= SEQUENCE {
    attestationVersion  200,
    attestationSecurityLevel  SecurityLevel,
    keyMintVersion  INTEGER,
    keyMintSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    uniqueId  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    hardwareEnforced  AuthorizationList,
}

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

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,
    mgfDigest  [203] EXPLICIT SET OF INTEGER OPTIONAL,
    rollbackResistance  [303] EXPLICIT NULL OPTIONAL,
    earlyBootOnly  [305] EXPLICIT NULL OPTIONAL,
    activeDateTime  [400] EXPLICIT INTEGER OPTIONAL,
    originationExpireDateTime  [401] EXPLICIT INTEGER OPTIONAL,
    usageExpireDateTime  [402] EXPLICIT INTEGER OPTIONAL,
    usageCountLimit  [405] EXPLICIT INTEGER OPTIONAL,
    noAuthRequired  [503] EXPLICIT NULL OPTIONAL,
    userAuthType  [504] EXPLICIT INTEGER OPTIONAL,
    authTimeout  [505] EXPLICIT INTEGER OPTIONAL,
    allowWhileOnBody  [506] EXPLICIT NULL OPTIONAL,
    trustedUserPresenceRequired  [507] EXPLICIT NULL OPTIONAL,
    trustedConfirmationRequired  [508] EXPLICIT NULL OPTIONAL,
    unlockedDeviceRequired  [509] EXPLICIT NULL OPTIONAL,
    creationDateTime  [701] EXPLICIT INTEGER OPTIONAL,
    origin  [702] EXPLICIT INTEGER OPTIONAL,
    rootOfTrust  [704] EXPLICIT RootOfTrust OPTIONAL,
    osVersion  [705] EXPLICIT INTEGER OPTIONAL,
    osPatchLevel  [706] EXPLICIT INTEGER OPTIONAL,
    attestationApplicationId  [709] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdBrand  [710] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdDevice  [711] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdProduct  [712] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdSerial  [713] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdImei  [714] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdMeid  [715] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdManufacturer  [716] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdModel  [717] EXPLICIT OCTET_STRING OPTIONAL,
    vendorPatchLevel  [718] EXPLICIT INTEGER OPTIONAL,
    bootPatchLevel  [719] EXPLICIT INTEGER OPTIONAL,
    deviceUniqueAttestation  [720] EXPLICIT NULL OPTIONAL,
}

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

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

Version 100

KeyDescription ::= SEQUENCE {
    attestationVersion  100,
    attestationSecurityLevel  SecurityLevel,
    keyMintVersion  INTEGER,
    keyMintSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    uniqueId  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    hardwareEnforced  AuthorizationList,
}

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

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,
    mgfDigest  [203] EXPLICIT SET OF INTEGER OPTIONAL,
    rollbackResistance  [303] EXPLICIT NULL OPTIONAL,
    earlyBootOnly  [305] EXPLICIT NULL OPTIONAL,
    activeDateTime  [400] EXPLICIT INTEGER OPTIONAL,
    originationExpireDateTime  [401] EXPLICIT INTEGER OPTIONAL,
    usageExpireDateTime  [402] EXPLICIT INTEGER OPTIONAL,
    usageCountLimit  [405] EXPLICIT INTEGER OPTIONAL,
    noAuthRequired  [503] EXPLICIT NULL OPTIONAL,
    userAuthType  [504] EXPLICIT INTEGER OPTIONAL,
    authTimeout  [505] EXPLICIT INTEGER OPTIONAL,
    allowWhileOnBody  [506] EXPLICIT NULL OPTIONAL,
    trustedUserPresenceRequired  [507] EXPLICIT NULL OPTIONAL,
    trustedConfirmationRequired  [508] EXPLICIT NULL OPTIONAL,
    unlockedDeviceRequired  [509] EXPLICIT NULL OPTIONAL,
    creationDateTime  [701] EXPLICIT INTEGER OPTIONAL,
    origin  [702] EXPLICIT INTEGER OPTIONAL,
    rootOfTrust  [704] EXPLICIT RootOfTrust OPTIONAL,
    osVersion  [705] EXPLICIT INTEGER OPTIONAL,
    osPatchLevel  [706] EXPLICIT INTEGER OPTIONAL,
    attestationApplicationId  [709] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdBrand  [710] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdDevice  [711] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdProduct  [712] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdSerial  [713] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdImei  [714] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdMeid  [715] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdManufacturer  [716] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdModel  [717] EXPLICIT OCTET_STRING OPTIONAL,
    vendorPatchLevel  [718] EXPLICIT INTEGER OPTIONAL,
    bootPatchLevel  [719] EXPLICIT INTEGER OPTIONAL,
    deviceUniqueAttestation  [720] EXPLICIT NULL OPTIONAL,
}

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

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

Version 4

KeyDescription ::= SEQUENCE {
    attestationVersion  4,
    attestationSecurityLevel  SecurityLevel,
    keymasterVersion  INTEGER,
    keymasterSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    uniqueId  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    hardwareEnforced  AuthorizationList,
}

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

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,
    rollbackResistance  [303] EXPLICIT NULL OPTIONAL,
    earlyBootOnly  [305] EXPLICIT NULL 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,
    trustedUserPresenceRequired  [507] EXPLICIT NULL OPTIONAL,
    trustedConfirmationRequired  [508] EXPLICIT NULL OPTIONAL,
    unlockedDeviceRequired  [509] EXPLICIT NULL OPTIONAL,
    allApplications  [600] EXPLICIT NULL OPTIONAL,
    creationDateTime  [701] EXPLICIT INTEGER OPTIONAL,
    origin  [702] EXPLICIT INTEGER OPTIONAL,
    rootOfTrust  [704] EXPLICIT RootOfTrust OPTIONAL,
    osVersion  [705] EXPLICIT INTEGER OPTIONAL,
    osPatchLevel  [706] EXPLICIT INTEGER OPTIONAL,
    attestationApplicationId  [709] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdBrand  [710] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdDevice  [711] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdProduct  [712] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdSerial  [713] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdImei  [714] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdMeid  [715] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdManufacturer  [716] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdModel  [717] EXPLICIT OCTET_STRING OPTIONAL,
    vendorPatchLevel  [718] EXPLICIT INTEGER OPTIONAL,
    bootPatchLevel  [719] EXPLICIT INTEGER OPTIONAL,
    deviceUniqueAttestation  [720] EXPLICIT NULL OPTIONAL,
}

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

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

Version 3

KeyDescription ::= SEQUENCE {
    attestationVersion  3,
    attestationSecurityLevel  SecurityLevel,
    keymasterVersion  INTEGER,
    keymasterSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    uniqueId  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    hardwareEnforced  AuthorizationList,
}

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

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,
    rollbackResistance  [303] EXPLICIT NULL 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,
    trustedUserPresenceRequired  [507] EXPLICIT NULL OPTIONAL,
    trustedConfirmationRequired  [508] EXPLICIT NULL OPTIONAL,
    unlockedDeviceRequired  [509] EXPLICIT NULL OPTIONAL,
    allApplications  [600] EXPLICIT NULL OPTIONAL,
    creationDateTime  [701] EXPLICIT INTEGER OPTIONAL,
    origin  [702] EXPLICIT INTEGER OPTIONAL,
    rootOfTrust  [704] EXPLICIT RootOfTrust OPTIONAL,
    osVersion  [705] EXPLICIT INTEGER OPTIONAL,
    osPatchLevel  [706] EXPLICIT INTEGER OPTIONAL,
    attestationApplicationId  [709] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdBrand  [710] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdDevice  [711] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdProduct  [712] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdSerial  [713] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdImei  [714] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdMeid  [715] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdManufacturer  [716] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdModel  [717] EXPLICIT OCTET_STRING OPTIONAL,
    vendorPatchLevel  [718] EXPLICIT INTEGER OPTIONAL,
    bootPatchLevel  [719] EXPLICIT INTEGER OPTIONAL,
}

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

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

Version 2

KeyDescription ::= SEQUENCE {
    attestationVersion  2,
    attestationSecurityLevel  SecurityLevel,
    keymasterVersion  INTEGER,
    keymasterSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    uniqueId  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    hardwareEnforced  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,
    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,
    attestationApplicationId  [709] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdBrand  [710] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdDevice  [711] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdProduct  [712] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdSerial  [713] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdImei  [714] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdMeid  [715] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdManufacturer  [716] EXPLICIT OCTET_STRING OPTIONAL,
    attestationIdModel  [717] EXPLICIT OCTET_STRING OPTIONAL,
}

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

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

Version 1

KeyDescription ::= SEQUENCE {
    attestationVersion  1,
    attestationSecurityLevel  SecurityLevel,
    keymasterVersion  INTEGER,
    keymasterSecurityLevel  SecurityLevel,
    attestationChallenge  OCTET_STRING,
    uniqueId  OCTET_STRING,
    softwareEnforced  AuthorizationList,
    hardwareEnforced  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,
    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,
}

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

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

KeyDescription fields

attestationVersion

The ASN.1 schema version.

Value	Keymaster/KeyMint 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 location where the attested key is stored.

keymasterVersion / keyMintVersion

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

Value	Keymaster/KeyMint version
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

The challenge provided at key generation time.

uniqueId

A privacy-sensitive device identifier that system apps can request at key generation time. If the unique ID is not requested, this field is empty. For details, see the Unique ID section.

softwareEnforced

The Keymaster/KeyMint authorization list that is enforced by the Android system. This information is collected or generated by code in the platform and is stored in the device's system partition. It can be trusted as long as the device is running an operating system that complies with the Android Platform Security Model (that is, the device's bootloader is locked and the verifiedBootState is Verified).

hardwareEnforced

The Keymaster/KeyMint authorization list that is enforced by the device's Trusted Execution Environment (TEE) or StrongBox. This information is collected or generated by code in the secure hardware and is not controlled by the platform. For example, information can come from the bootloader or through a secure communication channel that does not involve trusting the platform.

SecurityLevel values

The SecurityLevel value indicates the extent to which a Keystore-related element (for example, key pair and attestation) is resilient to attack.

Value	Meaning
Software	Secure as long as the device's Android system complies with the Android Platform Security Model (that is, the device's bootloader is locked and the verifiedBootState is Verified).
TrustedEnvironment	Secure as long as Trusted Execution Environment (TEE) is not compromised. The isolation requirements for TEEs are defined in sections 9.11 [C-1-1] through [C-1-4] of the Android Compatibility Definition Document. TEEs are highly resistant to remote compromise and moderately resistant to compromise by direct hardware attack.
StrongBox	Secure as long as StrongBox is not compromised. StrongBox is implemented in a secure element similar to a hardware security module. The implementation requirements for StrongBox are defined in section 9.11.2 of the Android Compatibility Definition Document. StrongBox is highly resistant to remote compromise and compromise by direct hardware attack (for example, physical tampering and side-channel attacks).

AuthorizationList fields

Each field corresponds to a Keymaster/KeyMint authorization tag from the AIDL interface specification. The specification is the source of truth about authorization tags: their meaning, the format of their contents, whether they are expected to appear in the softwareEnforced or hardwareEnforced fields in the KeyDescription object, whether they are mutually exclusive with other tags, etc. All AuthorizationList fields are optional.

Note: Some tags listed in the specification don't appear in the ASN.1 schema for the attestation extension because, for example, they are not applicable to asymmetric keys (for example, Tag::MIN_MAC_LENGTH, Tag::CALLER_NONCE) or have no meaning off-device (for example, Tag::USER_SECURE_ID).

Each field has an EXPLICIT context-specific tag equal to the Keymaster/KeyMint tag number, which enables a more compact representation of the data in the AuthorizationList. The ASN.1 parser must therefore know the expected data type for each context-specific tag. For example, Tag::USER_AUTH_TYPE is defined as ENUM | 504. In the attestation extension schema, the purpose field in the AuthorizationList is specified as userAuthType [504] EXPLICIT INTEGER OPTIONAL. Its ASN.1 encoding will therefore contain the context-specific tag 504 instead of the UNIVERSAL class tag for the ASN.1 type INTEGER, which is 10.

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

Present only in key attestation versions >= 2.

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

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

attestationIdBrand

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_BRAND Keymaster tag, which uses a tag ID value of 710.

attestationIdDevice

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_DEVICE Keymaster tag, which uses a tag ID value of 711.

attestationIdProduct

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_PRODUCT Keymaster tag, which uses a tag ID value of 712.

attestationIdSerial

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_SERIAL Keymaster tag, which uses a tag ID value of 713.

attestationIdImei

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_IMEI authorization tag, which uses a tag ID value of 714.

attestationIdMeid

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_MEID authorization tag, which uses a tag ID value of 715.

attestationIdManufacturer

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_MANUFACTURER authorization tag, which uses a tag ID value of 716.

attestationIdModel

Present only in key attestation versions >= 2.

Corresponds to the Tag::ATTESTATION_ID_MODEL authorization tag, which uses a tag ID value of 717.

vendorPatchLevel

Present only in key attestation versions >= 3.

Corresponds to the Tag::VENDOR_PATCHLEVEL authorization tag, which uses a tag ID value of 718.

Specifies the vendor image security patch level that must be installed on the device for this key to be used. The value appears in the form YYYYMMDD, representing the date of the vendor security patch. For example, if a key were generated on an Android device with the vendor's August 1, 2018 security patch installed, this value would be 20180801.

bootPatchLevel

Present only in key attestation versions >= 3.

Corresponds to the Tag::BOOT_PATCHLEVEL authorization tag, which uses a tag ID value of 719.

Specifies the kernel image security patch level that must be installed on the device for this key to be used. The value appears in the form YYYYMMDD, representing the date of the system security patch. For example, if a key were generated on an Android device with the system's August 5, 2018 security patch installed, this value would be 20180805.

deviceUniqueAttestation

Present only in key attestation versions >= 4.

Corresponds to the Tag::DEVICE_UNIQUE_ATTESTATION authorization tag, which uses a tag ID value of 720.

attestationIdSecondImei

Present only in key attestation versions >= 300.

Corresponds to the Tag::ATTESTATION_ID_SECOND_IMEI authorization tag, which uses a tag ID value of 723.

RootOfTrust fields

verifiedBootKey

A secure hash of the public key used to verify the integrity and authenticity of all code that executes during device boot up as part of Verified Boot. SHA-256 is recommended.

deviceLocked

Whether the device's bootloader is locked. true means that the device booted a signed image that was successfully verified by Verified Boot.

verifiedBootState

The device's Verified Boot state.

verifiedBootHash

A digest of all data protected by Verified Boot. For devices that use the Android Verified Boot reference implementation, this field contains the VBMeta digest.

VerifiedBootState values

Note: Verified might also mean that the OS is being run on an approved test device with an unlocked bootloader. These devices can report the Verified state only if an authorized user is logged in.

Value	Corresponding boot state	Meaning
Verified	GREEN	A full chain of trust extends from a hardware-protected root of trust to the bootloader and all partitions verified by Verified Boot. In this state, the verifiedBootKey field contains the hash of the embedded root of trust, which is the certificate embedded in the device's ROM by the device manufacturer in the factory.
SelfSigned	YELLOW	Same as Verified, except that the verification was done using a root of trust configured by the user instead of the root of trust embedded by the manufacturer in the factory. In this state, the verifiedBootKey field contains the hash of the public key configured by the user.
Unverified	ORANGE	The device's bootloader is unlocked, so a chain of trust cannot be established. The device can be freely modified, so the device's integrity must be verified by the user out-of-band. In this state the verifiedBootKey field contains 32 bytes of zeroes.
Failed	RED	The device failed verification. In this state, there are no guarantees about the contents of the other RootOfTrust fields.

AttestationApplicationId

This field reflects the Android platform's belief as to which apps are allowed to use the secret key material under attestation. It can contain multiple packages if and only if multiple packages share the same UID. The AttestationApplicationId field in AuthorizationList is of type OCTET_STRING and is 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 signing certificates. An app can have multiple signing key certificate chains. For each, the "leaf" certificate is digested and placed in the signature_digests field. The field name is misleading, since the digested data is the app's signing certificates, not the app signatures, because it is named for the Signature class returned by a call to getPackageInfo(). The following code snippet shows an example set:

{SHA256(PackageInfo.signature[0]), SHA256(PackageInfo.signature[1]), ...}
    

Unique ID

The Unique ID is a 128-bit value that identifies the device, but only for a limited period of time. The value is computed with:

HMAC_SHA256(T || C || R, HBK)

Where:

• T is the "temporal counter value", computed by dividing the value of Tag::CREATION_DATETIME by 2592000000, dropping any remainder. T changes every 30 days (2592000000 = 30 * 24 * 60 * 60 * 1000).
• C is the value of Tag::APPLICATION_ID
• R is 1 if Tag::RESET_SINCE_ID_ROTATION is present in the attest_params parameter to the attest_key call, or 0 if the tag is not present.
• HBK is a unique hardware-bound secret known to the Trusted Execution Environment and never revealed by it. The secret contains at least 128 bits of entropy and is unique to the individual device (probabilistic uniqueness is acceptable given the 128 bits of entropy). HBK should be derived from fused key material via HMAC or AES_CMAC.

Truncate the HMAC_SHA256 output to 128 bits.

Attestation keys and certificates

Two keys, one RSA and one ECDSA, and the corresponding certificate chains, are securely provisioned into the device.

Android 12 introduces Remote Key Provisioning, and Android 13 requires devices implement it. Remote Key Provisioning provides devices in the field with per app, ECDSA P256 attestation certificates. These certificates are shorter-lived than the factory-provisioned certificates.

Multiple IMEIs

Android 14 adds support for multiple IMEIs in the Android Key Attestation record. OEMs can implement this feature by adding a KeyMint tag for a second IMEI. It is becoming increasingly common for devices to have multiple cellular radios and OEMs can now support devices with two IMEIs.

OEMs are required to have a secondary IMEI, if present on their devices, to be provisioned to the KeyMint implementation(s) so that those implementations can attest to it in the same way they attest to the first IMEI

Provisioning information extension

The provisioning information extension has OID 1.3.6.1.4.1.11129.2.1.30. The extension provides information that's known about the device by the provisioning server.

Schema

The extension follows the following CDDL schema:

  {
        1 : int,   ; certificates issued
  }

The map is unversioned and new optional fields may be added.

certs_issued

An approximate number of certificates issued to the device in the last 30 days. This value can be used as a signal for potential abuse if the value is greater than average by some orders of magnitude.

ID attestation

Android 8.0 includes optional support for ID attestation for devices with Keymaster 3. ID attestation allows the device to provide proof of its hardware identifiers, such as serial number or IMEI. Although an optional feature, it is highly recommended that all Keymaster 3 implementations provide support for it because being able to prove the device's identity enables use cases such as true zero-touch remote configuration to be more secure (because the remote side can be certain it is talking to the right device, not a device spoofing its identity).

ID attestation works by creating copies of the device's hardware identifiers that only the Trusted Execution Environment (TEE) can access before the device leaves the factory. A user can unlock the device's bootloader and change the system software and the identifiers reported by the Android frameworks. The copies of the identifiers held by the TEE cannot be manipulated in this way, ensuring that device ID attestation only attests to the device's original hardware identifiers, thereby thwarting spoofing attempts.

The main API surface for ID attestation builds on top of the existing key attestation mechanism introduced with Keymaster 2. When requesting an attestation certificate for a key held by keymaster, the caller can request that the device's hardware identifiers be included in the attestation certificate's metadata. If the key is held in the TEE, the certificate chains back to a known root of trust. The recipient of such a certificate can verify that the certificate and its contents, including the hardware identifiers, were written by the TEE. When asked to include hardware identifiers in the attestation certificate, the TEE attests only to the identifiers held in its storage, as populated on the factory floor.

Storage properties

The storage that holds the device's identifiers needs to have these properties:

• The values derived from the device's original identifiers are copied to the storage before the device leaves the factory.
• The destroyAttestationIds() method can permanently destroy this copy of the identifier-derived data. Permanent destruction means the data is completely removed so neither a factory reset nor any other procedure performed on the device can restore it. This is especially important for devices where a user has unlocked the bootloader and changed the system software and modified the identifiers returned by Android frameworks.
• RMA facilities should have the ability to generate fresh copies of the hardware identifier-derived data. This way, a device that passes through RMA can perform ID attestation again. The mechanism used by RMA facilities must be protected so that users cannot invoke it themselves, as that would allow them to obtain attestations of spoofed IDs.
• No code other than Keymaster trusted app in the TEE is able to read the identifier-derived data kept in the storage.
• The storage is tamper-evident: If the content of the storage has been modified, the TEE treats it the same as if the copies of the content had been destroyed and refuses all ID attestation attempts. This is implemented by signing or MACing the storage as described below.
• The storage does not hold the original identifiers. Because ID attestation involves a challenge, the caller always supplies the identifiers to be attested. The TEE only needs to verify that these match the values they originally had. Storing secure hashes of the original values rather than the values enables this verification.

Construction

To create an implementation that has the properties listed above, store the ID-derived values in the following construction S. Do not store other copies of the ID values, excepting the normal places in the system, which a device owner can modify by rooting:

S = D || HMAC(HBK, D)

where:

• D = HMAC(HBK, ID1) || HMAC(HBK, ID2) || ... || HMAC(HBK, IDn)
• HMAC is the HMAC construction with an appropriate secure hash (SHA-256 recommended)
• HBK is a hardware-bound key not used for any other purpose
• ID1...IDn are the original ID values; association of a particular value to a particular index is implementation-dependent, as different devices have different numbers of identifiers
• || represents concatenation

Because the HMAC outputs are fixed size, no headers or other structure are required to be able to find individual ID hashes, or the HMAC of D. In addition to checking provided values to perform attestation, implementations need to validate S by extracting D from S, computing HMAC(HBK, D) and comparing it to the value in S to verify that no individual IDs were modified/corrupted. Also, implementations must use constant-time comparisons for all individual ID elements and the validation of S. Comparison time must be constant regardless of the number of IDs provided and the correct matching of any part of the test.

Hardware identifiers

ID attestation supports the following hardware identifiers:

1. Brand name, as returned by Build.BRAND in Android
2. Device name, as returned by Build.DEVICE in Android
3. Product name, as returned by Build.PRODUCT in Android
4. Manufacturer name, as returned by Build.MANUFACTURER in Android
5. Model name, as returned by Build.MODEL in Android
6. Serial number
7. IMEIs of all radios
8. MEIDs of all radios

To support device ID attestation, a device attests to these identifiers. All devices running Android have the first six and they are necessary for this feature to work. If the device has any integrated cellular radios, the device must also support attestation for the IMEIs and/or MEIDs of the radios.

ID attestation is requested by performing a key attestation and including the device identifiers to attest in the request. The identifiers are tagged as:

• ATTESTATION_ID_BRAND
• ATTESTATION_ID_DEVICE
• ATTESTATION_ID_PRODUCT
• ATTESTATION_ID_MANUFACTURER
• ATTESTATION_ID_MODEL
• ATTESTATION_ID_SERIAL
• ATTESTATION_ID_IMEI
• ATTESTATION_ID_MEID

The identifier to attest is a UTF-8 encoded byte string. This format applies to numerical identifiers, as well. Each identifier to attest is expressed as a UTF-8 encoded string.

If the device does not support ID attestation (or destroyAttestationIds() was previously called and the device can no longer attest its IDs), any key attestation request that includes one or more of these tags fails with ErrorCode::CANNOT_ATTEST_IDS.

If the device supports ID attestation and one or more of the above tags have been included in a key attestation request, the TEE verifies the identifier supplied with each of the tags matches its copy of the hardware identifiers. If one or more identifiers do not match, the entire attestation fails with ErrorCode::CANNOT_ATTEST_IDS. It is valid for the same tag to be supplied multiple times. This can be useful, for example, when attesting IMEIs: A device can have multiple radios with multiple IMEIs. An attestation request is valid if the value supplied with each ATTESTATION_ID_IMEI matches one of the device's radios. The same applies to all other tags.

If attestation is successful, the attested IDs is added to the attestation extension (OID 1.3.6.1.4.1.11129.2.1.17) of the issued attestation certificate, using the schema from above. Changes from the Keymaster 2 attestation schema are bolded, with comments.

Java API

This section is informational only. Keymaster implementers neither implement nor use the Java API. This is provided to help implementers understand how the feature is used by apps. System components might use it differently, which is why it's crucial this section not be treated as normative.

How app developers use attestation

• Creates a key generation request, specifying a key alias and key generation parameters for an EC or RSA key pair.
• Sets the "attestation challenge" for the request with KeyPairGenerator.setAttestationChallenge(byte[]). Provides challenge data and indicates that an attestation is requested. This value should be provided by the validating service and used to verify that an attestation certificate matches a given request. The value should be at least 16 bytes and should also be a nonce. If a challenge is ever reused, then your service might be vulnerable to replays of older attestation certificates.
• Generates the key pair.
• Requests the certificate chain from AndroidKeyStore. The first certificate in the chain is the attestation; the other certificates provide the chain of trust back to and including the root attestation key.

This example generates a key pair and requests an attestation.

// Create KeyPairGenerator and set generation parameters for an ECDSA key pair
// using the NIST P-256 curve.  "Key1" is the key alias.
KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
    KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
keyPairGenerator.initialize(
    new KeyGenParameterSpec.Builder("Key1", KeyProperties.PURPOSE_SIGN)
         .setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
         .setDigests(KeyProperties.DIGEST_SHA256,
                     KeyProperties.DIGEST_SHA384,
                     KeyProperties.DIGEST_SHA512)
         // Only permit the private key to be used if the user
         // authenticated within the last five minutes.
         .setUserAuthenticationRequired(true)
         .setUserAuthenticationValidityDurationSeconds(5 * 60)
         // Request an attestation with challenge "hello world".
         .setAttestationChallenge("hello world".getBytes("UTF-8"))
         .build());
// Generate the key pair. This will result in calls to both generate_key() and
// attest_key() at the keymaster2 HAL.
KeyPair keyPair = keyPairGenerator.generateKeyPair();
// Get the certificate chain
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
Certificate[] certs = keyStore.getCertificateChain("Key1");
// certs[0] is the attestation certificate. certs[1] signs certs[0], etc.,
// up to certs[certs.length - 1].