金鑰和 ID 認證

KeyStore 提供更安全的環境,可讓您以受控方式建立、儲存及使用加密編譯金鑰。當可使用並使用硬體支援的金鑰儲存空間時,金鑰內容的安全性就會提高,不易從裝置中擷取,而 Keymaster 會強制執行難以破壞的限制。

不過,只有在已知金鑰庫金鑰位於硬體支援儲存空間時,這項做法才適用。在 Keymaster 1 中,應用程式或遠端伺服器無法可靠地驗證是否發生這種情況。金鑰存放區守護程序會載入可用的 Keymaster HAL,並相信 HAL 針對金鑰的硬體支援所說的任何內容。

為解決這個問題,Keymaster 在 Android 7.0 (Keymaster 2) 中推出金鑰認證,並在 Android 8.0 (Keymaster 3) 中推出 ID 認證。

金鑰認證旨在提供一種方法來強力地判斷非對稱金鑰組是否採用硬體支援、金鑰的屬性,以及套用至該金鑰的限制。

ID 認證可讓裝置提供硬體 ID 的證明,例如序號或 IMEI。

金鑰認證

為支援金鑰認證,Android 7.0 為 HAL 引進一組標記、類型和方法。

標記

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

類型

Keymaster 2 以下版本

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

AttestKey 方法

Keymaster 3

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

Keymaster 2 以下版本

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 是 Keymaster 裝置結構。
  • keyToAttest 是從 generateKey 傳回的金鑰 Blob,系統會根據該 Blob 建立認證。
  • attestParams 是認證所需的任何參數清單。這包括 Tag::ATTESTATION_CHALLENGE 和可能的 Tag::RESET_SINCE_ID_ROTATION,以及 Tag::APPLICATION_IDTag::APPLICATION_DATA。如果在金鑰產生期間指定了金鑰 blob,則需要使用最後兩個方法才能解密金鑰 blob。
  • certChain 是輸出參數,會傳回憑證陣列。項目 0 是認證憑證,表示該憑證會認證 keyToAttest 中的金鑰,並包含認證擴充資料。

系統會將 attestKey 方法視為認證金鑰上的公開金鑰作業,因為隨時都可以呼叫此方法,不必符合授權限制。舉例來說,如果認證金鑰需要使用者驗證,則可在沒有使用者驗證的情況下產生認證。

認證證書

認證憑證是標準 X.509 憑證,其中包含選用的認證擴充資料,內含認證金鑰的說明。憑證會使用經過認證的認證金鑰簽署。認證金鑰可能會使用與認證金鑰不同的演算法。

認證憑證包含下表中的欄位,不得包含任何額外欄位。部分欄位會指定固定的欄位值。CTS 測試會驗證憑證內容是否完全符合定義。

憑證序列

欄位名稱 (請參閱 RFC 5280)
tbsCertificate TBSCertificate 序列
signatureAlgorithm 用於簽署金鑰的演算法演算法識別碼:
EC 金鑰的 ECDSA、RSA 金鑰的 RSA。
signatureValue 位元字串,在 ASN.1 DER 編碼 tbsCertificate 上計算的簽章。

TBSCertificate 序列

欄位名稱 (請參閱 RFC 5280)
version INTEGER 2 (代表 v3 憑證)
serialNumber INTEGER 1 (固定值:所有憑證皆相同)
signature 用於簽署金鑰的演算法 ID:ECDSA 用於 EC 金鑰,RSA 用於 RSA 金鑰。
issuer 與批次認證金鑰的主旨欄位相同。
validity 兩個日期的序列 (包含 Tag::ACTIVE_DATETIMETag::USAGE_EXPIRE_DATETIME 的值)。這些值是以毫秒為單位自 1970 年 1 月 1 日以來計算。如要瞭解憑證中日期的正確表示方式,請參閱 RFC 5280
如果沒有 Tag::ACTIVE_DATETIME,請使用 Tag::CREATION_DATETIME 的值。如果沒有 Tag::USAGE_EXPIRE_DATETIME,請使用批次認證金鑰憑證的到期日。
subject CN =「Android KeyStore Key」(固定值:所有憑證皆相同)
subjectPublicKeyInfo 含有認證公開金鑰的 SubjectPublicKeyInfo。
extensions/Key Usage digitalSignature:如果金鑰具有用途 KeyPurpose::SIGNKeyPurpose::VERIFY,則設為此值。未設定所有其他位元。
extensions/CRL Distribution Points 值 TBD
extensions/"attestation" OID 為 1.3.6.1.4.1.11129.2.1.17;內容定義請見下方的「認證擴充功能」一節。與所有 X.509 憑證擴充功能一樣,內容會以 OCTET_STRING 表示,其中包含認證序列的 DER 編碼。

認證擴充功能

attestation 擴充功能包含金鑰相關 Keymaster 授權的完整說明,該結構會直接對應到 Android 和 Keymaster HAL 中使用的授權清單。授權清單中的每個標記都以 ASN.1 SEQUENCE 項目表示,明確標記的 keymaster 標記編號,但類型描述元 (四個高階位元) 會被遮蓋。

舉例來說,在 Keymaster 3 中,Tag::PURPOSE 在 types.hal 中定義為 ENUM_REP | 1。對於認證擴充功能,系統會移除 ENUM_REP 值,只保留標記 1。(針對 Keymaster 2 以下版本,KM_TAG_PURPOSE 是在 keymaster_defs.h 中定義)。

根據下表,系統會以簡單的方式將值轉換為 ASN.1 類型:

Keymaster 類型 ASN.1 類型
ENUM INTEGER
ENUM_REP 整數集合
UINT INTEGER
UINT_REP 整數集合
ULONG INTEGER
ULONG_REP 整數集合
DATE INTEGER (自 1970 年 1 月 1 日 00:00:00 GMT 算起的毫秒數)
BOOL NULL (在 Keymaster 中,標記存在表示 true,不存在表示 false)。
(同樣的語意也適用於 ASN.1 編碼)
BIGNUM 目前未使用,因此未定義對應關係
BYTES 10 月 30 日

結構定義

認證擴充內容的說明如下 ASN.1 結構定義。

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),
}

版本 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),
}

版本 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),
}

版本 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),
}

版本 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),
}

版本 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),
}

版本 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 欄位

keymasterVersionattestationChallenge 欄位是以位置而非標記來識別,因此在已編碼表單中的標記只會指定欄位類型。其餘欄位會依照結構定義中的指定標記,以隱含方式標記。

欄位名稱 類型
attestationVersion INTEGER 認證結構定義版本:1、2 或 3。
attestationSecurity SecurityLevel 這項認證的安全性等級。您可以取得硬體支援金鑰的軟體認證。如果 Android 系統遭到入侵,就無法信任這類認證。
keymasterVersion INTEGER Keymaster 裝置的版本:0、1、2、3 或 4。
keymasterSecurity SecurityLevel Keymaster 實作的安全性等級。
attestationChallenge OCTET_STRING 指定給認證要求的 Tag::ATTESTATION_CHALLENGE 值。
uniqueId OCTET_STRING 選用的不重複 ID (如果鍵有 Tag::INCLUDE_UNIQUE_ID)
softwareEnforced AuthorizationList 非必要,不是 TEE 強制執行的 Keymaster 授權 (如有)。
teeEnforced AuthorizationList 由 TEE 強制執行的 Keymaster 授權 (如果有的話)。

AuthorizationList 欄位

AuthorizationList 欄位皆為選用欄位,並以 Keymaster 標記值識別,且類型位元會遭到遮蔽。使用明確標記,因此欄位也會包含表示 ASN.1 類型的標記,以方便剖析。

如要進一步瞭解每個欄位的值,請參閱 Keymaster 3 的 types.hal,以及 Keymaster 2 的 keymaster_defs.h。我們省略 KM_TAG 前置字串,並將其餘部分改為駝峰式大小寫,將 Keymaster 標記名稱轉換為欄位名稱,因此 Tag::KEY_SIZE 就變成了 keySize

RootOfTrust 欄位

RootOfTrust 欄位會以位置識別。

欄位名稱 類型
verifiedBootKey OCTET_STRING 用於驗證系統映像檔的金鑰安全雜湊。建議使用 SHA-256。
deviceLocked BOOLEAN 如果系統啟動載入程式處於鎖定狀態,則為 True,表示只能刷新已簽署的映像檔,且已完成驗證開機程序檢查。
verifiedBootState VerifiedBootState 驗證開機程序的狀態。
verifiedBootHash 10 月 30 日 由驗證開機程序保護的所有資料摘要。如果裝置使用的 Android 驗證開機程序,是透過驗證開機程序功能實作,則這個值包含「VBMeta 結構」摘要,或驗證開機程序的中繼資料結構摘要。如要進一步瞭解如何計算這個值,請參閱「VBMeta 摘要

VerifiedBootState 值

verifiedBootState 的值有以下含義:

意義
Verified 表示從系統啟動載入程式到已驗證的分區的完整信任鏈結,包括系統啟動載入程式、啟動分區和所有已驗證的分區。
在這個狀態下,verifiedBootKey 值是內嵌憑證的雜湊,代表 ROM 中已燒錄的不可變更憑證。
這個狀態與 驗證開機程序流程說明文件中所述的綠色啟動狀態相對應。
SelfSigned 表示啟動分區已使用內嵌憑證驗證,且簽章有效。在允許啟動程序繼續之前,Bootloader 會顯示警告和公開金鑰的指紋。
在這個狀態下,verifiedBootKey 值是自我簽署憑證的雜湊。
這個狀態對應至 驗證開機程序流程說明文件中的黃色啟動狀態。
Unverified 表示裝置可自由修改。裝置完整性則由使用者自行驗證。系統啟動載入程式會先向使用者顯示警告,然後才允許啟動程序繼續執行。
在這個狀態下,verifiedBootKey 值為空白。
這個狀態對應至 驗證開機程序流程說明文件中的橘色啟動狀態。
Failed 表示裝置驗證失敗。沒有認證憑證實際包含這個值,因為在這個狀態下,系統啟動載入程式會停止執行。我們在此提供完整資訊。
這個狀態與 驗證開機程序流程說明文件中的紅色啟動狀態相對應。

SecurityLevel 值

securityLevel 的值有以下含義:

意義
Software 建立或管理相關元素 (認證或金鑰) 的程式碼是在 Android 系統中實作,如果該系統遭到入侵,則可能會遭到竄改。
TrustedEnvironment 建立或管理相關元素 (認證或金鑰) 的程式碼已實作於受信任的執行環境 (TEE)。如果 TEE 遭到入侵,則可能會改變這項設定,但 TEE 能強力抵禦遠端入侵,且能抵禦直接硬體攻擊。
StrongBox 建立或管理相關元素 (認證或金鑰) 的程式碼是在專屬硬體安全性模組中實作。如果硬體安全模組遭到入侵,就可能會遭到竄改,但它可強力抵禦遠端入侵,以及直接硬體攻擊。

專屬 ID

專屬 ID 是 128 位元值,可用於識別裝置,但僅限於限定期間。計算值的方式如下:

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

其中:

  • T 是「時間計數器值」,計算方式是將 Tag::CREATION_DATETIME 的值除以 2592000000,並捨去任何餘數。T 每 30 天變更一次 (2592000000 = 30 * 24 * 60 * 60 * 1000)。
  • CTag::APPLICATION_ID 的值
  • 如果 attest_key 呼叫的 attest_params 參數含有 Tag::RESET_SINCE_ID_ROTATION,則 R 為 1,如果標記不存在,則為 0。
  • HBK 是受信任的執行環境已知的專屬硬體繫結密鑰,這個密鑰絕對不會顯示。密鑰包含至少 128 位元的熵,且該密鑰專屬於個別裝置 (由於熵長度為 128 位元,可接受的機率不重複性)。HBK 應透過 HMAC 或 AES_CMAC 從融合金鑰內容衍生。

將 HMAC_SHA256 輸出內容截斷為 128 位元。

認證金鑰和憑證

兩個金鑰 (一個 RSA 和一個 ECDSA) 和對應的憑證鏈結已安全地佈建至裝置。

Android 12 推出了遠端金鑰佈建功能,Android 13 則需要裝置實作這項功能。遠端金鑰佈建功能會為現場裝置提供每個應用程式的 ECDSA P256 認證憑證。這類憑證的效期比原廠佈建的憑證還短。

多個 IMEI

Android 14 新增了對 Android 金鑰認證記錄中多個 IMEI 的支援。如要實作這項功能,原始設備製造商 (OEM) 可以新增第二個 IMEI 的 KeyMint 標記。裝置擁有多個行動電台的情況越來越普遍,而原始設備製造商 (OEM) 現可支援裝置的兩個 IMEI。

OEM 必須具備次要 IMEI(如果裝置上有此資訊),並將其配置給 KeyMint 實作項目,以便這些實作項目能以與驗證第一個 IMEI 相同的方式驗證次要 IMEI。

ID 認證

Android 8.0 提供 ID 認證的選用支援功能,適用於搭載 Keymaster 3 的裝置。裝置可透過 ID 認證提供硬體 ID (例如序號或 IMEI) 的證明。雖然這是選用功能,但強烈建議所有 Keymaster 3 實作項目都支援這項功能,因為只要能證明裝置的身分,就能強化各種使用情境 (例如真正的零接觸遠端設定),讓裝置與正確的裝置通訊,不會假冒裝置的身分。

ID 認證機制會建立裝置硬體 ID 的副本,並在裝置離開工廠前,只允許信任執行環境 (TEE) 存取這些副本。使用者可以解鎖裝置的引導程序,並變更系統軟體和 Android 架構回報的 ID。TEE 持有的 ID 副本無法以這種方式操控,可確保裝置 ID 認證只會認證裝置的原始硬體 ID,進而防範假冒攻擊。

身分認證的主要 API 途徑會在 Keymaster 2 推出的現有金鑰認證機制上建構。針對 Keymaster 持有的金鑰要求認證憑證時,呼叫端可以要求將裝置硬體 ID 納入認證憑證的中繼資料。如果金鑰儲存在 TEE 中,憑證鏈結會回到已知的信任根。此類憑證的接收者可以驗證憑證及其內容 (包括硬體 ID) 是否由 TEE 編寫。當系統要求在認證證明書中加入硬體 ID 時,TEE 只會針對工廠填入的儲存裝置 ID 進行認證。

儲存空間屬性

儲存裝置 ID 的儲存空間必須具備下列屬性:

  • 系統會在裝置離開原廠設定前,將衍生自裝置原始 ID 的值複製到儲存空間。
  • destroyAttestationIds() 方法可以永久刪除這個 ID 衍生資料副本。永久銷毀資料,表示資料已完全移除,因此無論是恢復原廠設定或在裝置上執行的任何其他程序,都無法還原資料。如果使用者已解鎖系統啟動載入程式,並變更系統軟體並修改 Android 架構傳回的 ID,這一點就格外重要。
  • 退貨授權 (RMA) 設施應具備產生硬體 ID 衍生資料的新副本的功能。這樣一來,通過退貨授權的裝置就能再次執行身分認證。RMA 設施使用的機制必須受到保護,以免使用者自行叫用,因為這樣一來,使用者就能取得偽造 ID 的認證。
  • 除了 TEE 中的 Keymaster 信任應用程式外,其他程式碼都無法讀取儲存空間中儲存的 ID 衍生資料。
  • 儲存空間內容遭到竄改,如果儲存空間內容遭到修改,TEE 會將儲存的內容視為已刪除內容複本,並拒絕所有 ID 認證嘗試。這項功能的實作方式是簽署或使用 MAC 加密儲存空間,詳情請參閱下文
  • 儲存空間不會保存原始 ID,由於 ID 認證涉及挑戰,因此呼叫端一律會提供要認證的 ID。TEE 只需要驗證這些值是否與原始值相符。儲存原始值的安全雜湊值,而非值,即可啟用這項驗證。

營造業

如要建立具有上述屬性的實作,請將 ID 衍生值儲存在下列建構 S 中。請勿儲存其他 ID 值副本,但可儲存在系統中可供裝置擁有者透過 Root 權限修改的一般位置:

S = D || HMAC(HBK, D)

其中:

  • D = HMAC(HBK, ID1) || HMAC(HBK, ID2) || ... || HMAC(HBK, IDn)
  • HMAC 是 HMAC 結構體,搭配適當的安全雜湊 (建議使用 SHA-256)
  • HBK 是硬體綁定的鍵,不能用於其他用途
  • ID1...IDn 是原始 ID 值;將特定值與特定索引建立關聯的方式取決於實作方式,因為不同裝置的 ID 數量不同
  • || 表示串連

由於 HMAC 輸出內容的大小是固定大小,因此無需標頭或其他結構就能找出個別 ID 雜湊或 D 的 HMAC。除了檢查提供的值來執行認證外,實作還必須從 S 擷取 D、計算 HMAC(HBK, D) 並與 S 中的值進行比較,藉此驗證 S,確認沒有個別 ID 遭到修改或損毀。此外,實作項目必須對所有個別 ID 元素和 S 驗證使用常數比較。無論提供的 ID 數量和任何測試部分的正確比對為何,比較時間都必須是固定的。

硬體 ID

ID 認證支援下列硬體 ID:

  1. 品牌名稱,由 Android 中的 Build.BRAND 傳回
  2. Android 中的 Build.DEVICE 傳回的裝置名稱
  3. 產品名稱,由 Android 中的 Build.PRODUCT 傳回
  4. 由 Android 中的 Build.MANUFACTURER 傳回的製造商名稱
  5. 在 Android 中由 Build.MODEL 傳回的型號名稱
  6. 序號
  7. 所有無線電的 IMEI
  8. 所有無線通訊配備的 MEID

為支援裝置 ID 認證,裝置會對這些 ID 進行認證。所有搭載 Android 的裝置都具備前六項,且必須具備這些功能才能使用這項功能。如果裝置有任何整合式行動對講機,則必須支援對講機的 IMEI 和/或 MEID 認證。

系統會透過執行金鑰認證,並在要求中加入要認證的裝置 ID,來要求 ID 認證。這些 ID 會標記為:

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

要認證的 ID 是 UTF-8 編碼的位元組字串。這種格式也適用於數字 ID。每個要認證的 ID 都會以 UTF-8 編碼的字串表示。

如果裝置不支援 ID 認證 (或先前已呼叫 destroyAttestationIds(),且裝置無法再認證其 ID),則任何包含一或多個這些標記的金鑰認證要求都會失敗,並顯示 ErrorCode::CANNOT_ATTEST_IDS

如果裝置支援 ID 認證,且一或多個上述標記已納入金鑰認證要求,TEE 會驗證每個標記提供的 ID 是否與硬體 ID 副本相符。如果有一或多個 ID 不符,整個認證程序就會失敗,並顯示 ErrorCode::CANNOT_ATTEST_IDS。同一個標記可多次提供。這在認證 IMEI 時很有用,例如一個裝置可以有多個無線電和多個 IMEI 的無線電。如果每個 ATTESTATION_ID_IMEI 提供的值與裝置的其中一個無線電相符,認證要求就有效。所有其他標記也適用相同的做法。

如果認證成功,系統會使用上述結構定義,將認證 ID 新增至已核發認證憑證的認證擴充功能 (OID 1.3.6.1.4.1.11129.2.1.17)。與 Keymaster 2 認證結構定義的變更內容會以粗體字顯示,並附上註解。

Java API

本節僅提供相關資訊,Keymaster 實作者既不會實作也不會使用 Java API。這項資訊可協助導入者瞭解應用程式如何使用這項功能。系統元件可能會以不同的方式使用它,因此請務必不要將本節視為規範。