Keymaster 授權標籤

此頁面提供了幫助 Keymaster HAL 實施者的詳細資訊。它涵蓋了 HAL 中的每個標籤、該標籤在哪個 Keymaster 版本中可用,以及該標籤是否可重複。除了標籤描述中註明的之外,下面的所有標籤都在密鑰產生過程中使用來指定密鑰特徵。

對於 Keymaster 4,標籤在platform/hardware/interfaces/keymaster/ keymaster-version /types.hal中定義,例如 Keymaster 3 的3.0/types.hal和 Keymaster 4 的4.0/types.hal 。對於Keymaster 2 及更低版本,標籤在platform/hardware/libhardware/include/hardware/keymaster_defs.h定義。

有關功能,請參閱Keymaster 功能頁面。

標籤::ACTIVE_DATETIME

版本:1、2、3、4

可重複?不

指定密鑰變為活動狀態的日期和時間。在此之前,任何使用該金鑰的嘗試都會失敗,並顯示ErrorCode::KEY_NOT_YET_VALID

該值是一個 64 位元整數,表示自 1970 年 1 月 1 日以來的毫秒數。

標籤::演算法

版本:1、2、3、4

可重複?不

指定使用密鑰的加密演算法。

可能的值由以下枚舉定義:

Keymaster 3
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 及更早版本
typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

標籤::ALL_APPLICATIONS

版本:1、2、3、4

可重複?不

保留以供將來使用。

標籤::ALLOW_WHILE_ON_BODY

版本:2、3、4

可重複?不

此標籤僅適用於具有身體感應器的 Android Wear 裝置。目前,預計任何 TEE 都無法提供對人體感測器的安全訪問,或者人體感測器非常安全,因此這預計將是純粹的軟體強制功能。

標籤::ALL_USERS

版本:3、4

可重複?不

保留以供將來使用。

標籤::APPLICATION_DATA

版本:1、2、3、4

可重複?不

當提供給generateKeyimportKey時,此標籤指定在金鑰的所有使用過程中必需的資料。特別是,對exportKeygetKeyCharacteristics的呼叫需要向clientId參數提供相同的值,並且對begin的呼叫需要提供此標記和相同的關聯資料作為inParams集的一部分。如果未提供正確的數據,函數將傳回ErrorCode::INVALID_KEY_BLOB

該標籤的內容以加密方式綁定到金鑰,這意味著有權訪問所有安全世界秘密但無權訪問標籤內容的對手在不暴力破解標籤的情況下不可能解密金鑰應用程式可以透過指定足夠高熵的內容來阻止這些內容。

該值是一個 blob,一個任意長度的位元組數組。

標籤::APPLICATION_ID

版本:1、2、3、4

可重複?不

當提供給generateKeyimportKey時,此標籤指定在金鑰的所有使用過程中必需的資料。特別是,對exportKeygetKeyCharacteristics的呼叫需要在clientId參數中提供相同的值,並且對begin的呼叫需要提供此標記和相同的關聯資料作為inParams集的一部分。如果未提供正確的數據,函數將傳回ErrorCode::INVALID_KEY_BLOB

該標籤的內容以加密方式綁定到金鑰,這意味著對手可以存取所有安全世界的秘密,但無權存取標籤內容,無法解密金鑰(無需暴力破解標籤內容) )。

該值是一個 blob,一個任意長度的位元組數組。

標籤::ASSOCIATED_DATA

版本:1、2、3、4

可重複?不

為 AES-GCM 加密或解密提供「關聯資料」。提供此標籤是為了更新和指定未加密/解密但用於計算 GCM 標籤的資料。

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_APPLICATION_ID

版本:3、4

可重複?不

用於識別已啟動密鑰證明的一組可能的應用程式。

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_CHALLENGE

版本:3、4

可重複?不

用於提供認證挑戰。

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_BRAND

版本:3、4

可重複?不

提供裝置的品牌名稱,由 Android 中的Build.BRAND傳回。僅當請求證明裝置識別碼時才設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_DEVICE

版本:3、4

可重複?不

提供裝置的裝置名稱,由 Android 中的Build.DEVICE傳回。僅當請求證明裝置識別碼時才設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_IMEI

版本:3、4

可重複?是的

提供設備上所有無線電的 IMEI。僅當請求證明裝置識別碼時才設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_MANUFACTURER

版本:3、4

可重複?不

提供設備的製造商名稱,由 Android 中的Build.MANUFACTURER返回。僅當請求證明裝置識別碼時才設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_MEID

版本:3、4

可重複?是的

提供設備上所有無線電的 MEID。僅當請求裝置識別碼的證明時才會設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_MODEL

版本:3、4

可重複?不

提供裝置的型號名稱,由 Android 中的Build.MODEL返回。僅當請求證明裝置識別碼時才設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_Product

版本:3、4

可重複?不

提供裝置的產品名稱,由 Android 中的Build.PRODUCT傳回。僅當請求證明裝置識別碼時才設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::ATTESTATION_ID_SERIAL

版本:3、4

可重複?不

提供設備的序號。僅當請求證明裝置識別碼時才設定此欄位。

如果裝置不支援 ID 證明(或先前呼叫了destroyAttestationIds()且裝置無法再證明其 ID),則任何包含此標記的金鑰證明請求都會失敗,並顯示ErrorCode::CANNOT_ATTEST_IDS

該值是一個 blob,一個任意長度的位元組數組。

標籤::AUTH_TIMEOUT

版本:1、2、3、4

可重複?不

指定身份驗證後授權使用金鑰的時間(以秒為單位)。如果存在Tag::USER_SECURE_ID而該標籤不存在,則每次使用時都需要對密鑰進行身份驗證(有關每次操作身份驗證流程的詳細信息,請參閱開頭)。

該值是一個 32 位元整數,指定對Tag::USER_SECURE_ID指定的使用者使用Tag::USER_AUTH_TYPE指定的驗證方法成功進行驗證後可以使用金鑰的時間(以秒為單位)。

標籤::AUTH_TOKEN

版本:1、2、3、4

可重複?不

提供用於beginupdatefinish 的身份驗證令牌,以證明需要它的密鑰操作的用戶身份驗證(密鑰具有Tag::USER_SECURE_ID )。

該值是一個包含hw_auth_token_t結構的 blob。

標籤::BLOB_USAGE_REQUIREMENTS

版本:1、2、3、4

可重複?不

指定要使用產生的金鑰所需的系統環境條件。

可能的值由以下枚舉定義:

Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 及更早版本
typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

此標籤可以在金鑰產生期間指定,以要求金鑰在指定條件下可用。它需要與來自generateKeygetKeyCharacteristics的關鍵特徵一起返回。如果呼叫方指定Tag::BLOB_USAGE_REQUIREMENTS的值為KeyBlobUsageRequirements::STANDALONE則 trustlet 將傳回一個無需檔案系統支援即可使用的金鑰 blob。這對於具有加密磁碟的裝置至關重要,因為在使用 Keymaster 金鑰解密磁碟之前,檔案系統可能不可用。

標籤::BLOCK_MODE

版本:1、2、3、4

可重複?是的

指定密鑰可以使用的分組密碼模式。此標籤僅與 AES 金鑰相關。

可能的值由以下枚舉定義:

Keymaster 3
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 及更早版本
typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

此標記是可重複的,並且對於 AES 金鑰操作,請在beginadditionalParams參數中指定模式。如果指定的模式不在與該鍵關聯的模式中,則操作將失敗並傳回ErrorCode::INCOMPATIBLE_BLOCK_MODE

標籤::BOOT_PATCHLEVEL

版本:4

Tag::BOOT_PATCHLEVEL 指定可以使用金鑰的啟動映像(核心)安全性修補程式等級。該標籤永遠不會傳送給金鑰主控 TA,而是由 TA 新增至硬體強制授權清單。任何嘗試使用Tag::BOOT_PATCHLEVEL值與目前運行的系統補丁等級不同的金鑰都會導致begin()getKeyCharacteristics()exportKey()傳回ErrorCode::KEY_REQUIRES_UPGRADE 。詳細資訊請參閱upgradeKey()

標記的值是 YYYYMMDD 形式的整數,其中 YYYY 是上次更新的四位數年份,MM 是兩位數月份,DD 是上次更新的兩位數日期。例如,對於在 2018 年 6 月 5 日最後更新的 Android 裝置上產生的金鑰,該值將為 20180605。如果不知道該日期,則可以替換為 00。

在每次引導期間,引導程式必須向安全環境提供引導映像的修補程式等級(機制是實作定義的)。

必須由硬體強制執行。

標籤::BOOTLOADER_ONLY

版本:1、2、3、4

可重複?不

指定只有引導程式可以使用該金鑰。

此標籤是布林值,因此可能的值為 true(如果標籤存在)和 false(如果標籤不存在)。

任何從 Android 系統使用Tag::BOOTLOADER_ONLY密鑰的嘗試都會失敗,並顯示ErrorCode::INVALID_KEY_BLOB

標籤::CALLER_NONCE

版本:1、2、3、4

可重複?不

指定呼叫者可以為需要隨機數的操作提供隨機數。

此標籤是布林值,因此可能的值為 true(如果標籤存在)和 false(如果標籤不存在)。

此標籤僅用於 AES 金鑰,並且僅與 CBC、CTR 和 GCM 區塊模式相關。如果標記不存在,實作應拒絕任何提供Tag::NONCEErrorCode::CALLER_NONCE_PROHIBITED開頭的操作。

標籤::CREATION_DATETIME

版本:1、2、3、4

可重複?不

指定建立金鑰的日期和時間(自 1970 年 1 月 1 日起以毫秒為單位)。此標記是可選的,僅供參考。

標籤::摘要

版本:1、2、3、4

可重複?是的

指定可與金鑰一起使用以執行簽署和驗證操作的摘要演算法。此標籤與 RSA、ECDSA 和 HMAC 金鑰相關。

可能的值由以下枚舉定義:

Keymaster 3
enum class Digest : uint32_t {
    NONE = 0,
    MD5 = 1,
    SHA1 = 2,
    SHA_2_224 = 3,
    SHA_2_256 = 4,
    SHA_2_384 = 5,
    SHA_2_512 = 6,
};
Keymaster 2 及更早版本
typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

該標籤是可重複的。對於簽章和驗證操作,請在beginadditionalParams參數中指定摘要。如果指定的摘要不在與金鑰關聯的摘要中,則操作將會失敗並顯示ErrorCode::INCOMPATIBLE_DIGEST

標籤::EC_CURVE

版本:2、3、4

可重複?不

在 Keymaster 1 中,用於 EC 金鑰的曲線是根據指定的金鑰大小猜測的。為了提高未來的靈活性,Keymaster 2 引入了一種明確的方法來指定曲線。 EC 密鑰產生請求可能具有Tag::EC_CURVETag::KEY_SIZE或兩者。

可能的值由以下枚舉定義:

Keymaster 3
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 及更早版本
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

如果產生要求僅包含Tag::KEY_SIZE ,則回退到 Keymaster 1 邏輯,選擇適當的 NIST 曲線。

如果請求僅包含Tag::EC_CURVE ,則使用指定的曲線。對於 Keymaster 3 及更高版本,曲線在EcCurve中定義。對於 Keymaster 2 及更早版本,曲線在keymaster_ec_curve_t中定義。

如果請求包含兩者,請使用Tag::EC_CURVE指定的曲線,並驗證指定的金鑰大小是否適合該曲線。如果不是,則傳回ErrorCode::INVALID_ARGUMENT

標籤::INCLUDE_UNIQUE_ID

版本:2、3、4

可重複?不

此標記在密鑰產生期間指定,以指示產生的密鑰的證明證書應包含應用程式範圍和時間限制的設備唯一 ID,如Tag::UNIQUE_ID所指定。

此標籤是布林值,因此可能的值為 true(如果標籤存在)和 false(如果標籤不存在)。

標籤::KEY_SIZE

版本:1、2、3、4

可重複?不

指定密鑰的大小(以位元為單位),以密鑰演算法的正常方式測量。例如,對於 RSA 金鑰, Tag::KEY_SIZE指定公共模數的大小。對於 AES 金鑰,它指定金鑰材料的長度。

標籤::MAC_LENGTH

版本:1、2、3、4

可重複?不

提供所要求的 MAC 或 GCM 驗證標記的長度(以位元為單位)。

該值是以位元為單位的 MAC 長度。它是 8 的倍數,至少與與金鑰關聯的Tag::MIN_MAC_LENGTH的值一樣大。

標籤::MAX_USES_PER_BOOT

版本:1、2、3、4

可重複?不

指定在系統重新引導之間可以使用密鑰的最大次數。這是限制密鑰使用速率的另一種機制。

該值是一個 32 位元整數,表示每次啟動的使用情況。

當在操作中使用帶有此標記的鍵時,與鍵相關的計數器應在開始呼叫期間遞增。密鑰計數器超過此值後,所有後續使用該密鑰的嘗試都會失敗並顯示ErrorCode::MAX_OPS_EXCEEDED ,直到裝置重新啟動。這表示 trustlet 會為帶有此標籤的金鑰保留一個使用計數器表。由於 Keymaster 記憶體通常有限,因此該表可以具有固定的最大大小,並且當表已滿時,嘗試使用帶有此標記的密鑰的操作可能會失敗。該桌子至少需要容納 16 個鑰匙。如果操作因表已滿而失敗,Keymaster 將傳回ErrorCode::TOO_MANY_OPERATIONS

標籤::MIN_MAC_LENGTH

版本:1、2、3、4

可重複?不

此標籤指定對於支援 GCM 模式的 HMAC 金鑰和 AES 金鑰,可以使用此金鑰請求或驗證的 MAC 的最小長度。

該值是最小 MAC 長度(以位元為單位)。它是 8 的倍數。對於 HMAC 金鑰,該值至少為 64。對於 GCM 金鑰,該值至少為 96 且不大於 128。

標籤::MIN_SECONDS_BETWEEN_OPS

版本:1、2、3、4

可重複?不

指定允許使用密鑰進行的操作之間經過的最短時間。這可用於在無限制使用可能導致暴力攻擊的情況下對金鑰的使用進行速率限制。

該值是一個 32 位元整數,表示允許的操作之間的秒數。

當在操作中使用帶有此標記的鍵時,在完成中止呼叫期間啟動計時器。在計時器之前收到的任何開始呼叫都表示Tag::MIN_SECONDS_BETWEEN_OPS指定的時間間隔已過,失敗並傳回ErrorCode::KEY_RATE_LIMIT_EXCEEDED 。這表示 trustlet 會為帶有此標籤的金鑰保留一個使用計數器表。由於 Keymaster 記憶體通常有限,因此該表可以具有固定的最大大小,並且當表已滿時,嘗試使用帶有此標記的密鑰的操作可能會失敗。此表需要容納至少 32 個正在使用的密鑰,並在密鑰最小使用間隔到期時積極重複使用表槽。如果操作因表已滿而失敗,Keymaster 將傳回ErrorCode::TOO_MANY_OPERATIONS

標籤::NO_AUTH_REQUIRED

版本:1、2、3、4

可重複?不

指定使用此金鑰不需要任何身份驗證。該標籤與Tag::USER_SECURE_ID互斥。

此標籤是布林值,因此可能的值為 true(如果標籤存在)和 false(如果標籤不存在)。

標籤::隨機數

版本:1、2、3、4

可重複?不

提供或傳回用於 AES GCM、CBC 或 CTR 加密或解密的隨機數或初始化向量 (IV)。該標籤是在加密和解密操作期間開始提供的。僅當密鑰具有Tag::CALLER_NONCE時才提供開始。如果未提供,Keymaster 將隨機產生適當的隨機數或 IV,並從開始時傳回。

該值是一個 blob,一個任意長度的位元組數組。允許的長度取決於模式:GCM 隨機數的長度為 12 個位元組; CBC 和 CTR IV 的長度為 16 位元組。

標籤::起源

版本:1、2、3、4

可重複?不

指定密鑰的建立位置(如果已知)。此標籤在金鑰產生或匯入期間可能不會指定,且必須由 trustlet 新增至金鑰特徵。

鑰匙大師3

可能的值在android::hardware::keymaster::v3_0::KeyOrigin中定義:

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 及更早版本

可能的值在keymaster_origin_t中定義:

typedef enum {
    KM_ORIGIN_GENERATED = 0,
    KM_ORIGIN_IMPORTED = 2,
    KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t

該值的完整含義不僅取決於該值,還取決於它是在硬體強制的特徵列表中還是在軟體強制的特徵列表中找到。

GENERATED表示 Keymaster 產生了金鑰。如果在硬體強制清單中,則金鑰是在安全硬體中產生的,並且是永久硬體綁定的。如果在軟體強制清單中,則金鑰是在 SoftKeymaster 中產生的,且不受硬體限制。

DERIVED表示金鑰是在 Keymaster 內部派生的。可能存在於設備外。

IMPORTED表示金鑰是在 Keymaster 外部產生並導入 Keymaster 中的。如果在硬體強制清單中,則它是永久硬體綁定的,儘管可能存在安全硬體之外的副本。如果在軟體強制清單中,則金鑰已匯入 SoftKeymaster 並且不受硬體綁定。

UNKNOWN應該只出現在硬體強制清單中。它表明密鑰是硬體綁定的,但不知道密鑰是最初在安全硬體中產生的還是導入的。只有在使用 keymaster0 硬體模擬 keymaster1 服務時才會發生這種情況。

標籤::ORIGINATION_EXPIRE_DATETIME

版本:1、2、3、4

可重複?不

指定用於簽署和加密目的的金鑰到期的日期和時間。此後,任何嘗試使用提供的KeyPurpose::SIGNKeyPurpose::ENCRYPT開始的金鑰都會失敗,並顯示ErrorCode::KEY_EXPIRED

該值是一個 64 位元整數,表示自 1970 年 1 月 1 日以來的毫秒數。

標籤::OS_PATCHLEVEL

版本:2、3、4

可重複?不

該標籤永遠不會傳送給金鑰主控 TA,而是由 TA 新增至硬體強制授權清單。

標記的值是 YYYYMM 形式的整數,其中 YYYY 是上次更新的四位數年份,MM 是上次更新的兩位數月份。例如,對於上次更新於 2015 年 12 月的 Android 裝置上產生的金鑰,該值將為 201512。

補丁等級與目前補丁等級不同的金鑰不可用。嘗試使用此類鍵會導致begingetKeyCharacteristicsexportKey傳回ErrorCode::KEY_REQUIRES_UPGRADE 。有關更多詳細信息,請參閱版本綁定

標籤::OS_VERSION

版本:2、3、4

可重複?不

該標籤永遠不會傳送給金鑰主控 TA,而是由 TA 新增至硬體強制授權清單。

標記的值是 MMmmss 形式的整數,其中 MM 是主版本號,mm 是次版本號,ss 是次次版本號。例如,對於在 Android 版本 4.0.3 上產生的金鑰,該值將為 040003。

標籤::填充

版本:1、2、3、4

可重複?是的

指定可與鍵一起使用的填滿模式。此標籤與 RSA 和 AES 金鑰相關。

可能的值由以下枚舉定義:

Keymaster 3
enum class PaddingMode : uint32_t {
    NONE = 1,
    RSA_OAEP = 2,
    RSA_PSS = 3,
    RSA_PKCS1_1_5_ENCRYPT = 4,
    RSA_PKCS1_1_5_SIGN = 5,
    PKCS7 = 64,
};
Keymaster 2 及更早版本
typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEPPaddingMode::RSA_PKCS1_1_5_ENCRYPT僅用於 RSA 加密/解密金鑰,並分別指定 RSA PKCS#1v2 OAEP 填入和 RSA PKCS#1 v1.5 隨機填入。 PaddingMode::RSA_PSSPaddingMode::RSA_PKCS1_1_5_SIGN僅用於 RSA 簽章/驗證金鑰,並分別指定 RSA PKCS#1v2 PSS 填入和 RSA PKCS#1 v1.5 確定性填入。

PaddingMode::NONE可以與 RSA 或 AES 金鑰一起使用。對於 AES 金鑰,如果PaddingMode::NONE與區塊模式 ECB 或 CBC 一起使用,並且要加密或解密的資料的長度不是 AES 區塊大小的倍數,則對 finish 的呼叫將失敗並傳回ErrorCode::INVALID_INPUT_LENGTH

PaddingMode::PKCS7只能與 AES 金鑰一起使用,並且只能與 EC​​B 和 CBC 模式一起使用。

該標籤是可重複的。必須在開始呼叫中指定填充模式。如果指定的模式未獲得該金鑰的授權,則操作將失敗並傳回ErrorCode::INCOMPATIBLE_BLOCK_MODE

標籤::目的

版本:1、2、3、4

可重複?是的

指定密鑰可用於的一組用途。

可能的值由以下枚舉定義:

Keymaster 3
enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};
Keymaster 2 及更早版本
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

該標籤是可重複的;儘管操作具有單一目的,但可以使用多個值產生鍵。當呼叫begin函數來開始一項操作時,就指定了該操作的目的。如果指定給操作的目的未經金鑰授權,則操作將失敗並傳回ErrorCode::INCOMPATIBLE_PURPOSE

標籤::RESET_SINCE_ID_ROTATION

版本:3、4

可重複?不

指定自上次唯一 ID 輪替後設備是否已恢復原廠設定。用於密鑰證明。

此標籤是布林值,因此可能的值為 true(如果標籤存在)和 false(如果標籤不存在)。

標籤::ROLLBACK_RESISTANT

版本:1、2、3、4

可重複?不

表示該金鑰是防回滾的,表示當透過deleteKeydeleteAllKeys刪除時,該金鑰保證被永久刪除並且無法使用。沒有此標籤的金鑰可能會被刪除,然後從備份中還原。

此標籤是布林值,因此可能的值為 true(如果標籤存在)和 false(如果標籤不存在)。

標籤::ROOT_OF_TRUST

版本:1、2、3、4

可重複?不

指定信任根,即驗證啟動用來驗證啟動的作業系統(如果有)的金鑰。在金鑰特性中,此標籤永遠不會提供給 Keymaster 或從 Keymaster 傳回。

標籤::RSA_PUBLIC_EXPONENT

版本:1、2、3、4

可重複?不

指定 RSA 金鑰對的公共指數值。此標籤僅與 RSA 金鑰相關,並且對於所有 RSA 金鑰都是必要的。

值為64位元無符號整數,滿足RSA公共指數的要求。該值必須是質數。 Trustlet 支援值 2^16+1 並且可能支援其他合理值,特別是值 3。如果未指定指數或不支援指定的指數,則金鑰產生將失敗並顯示ErrorCode::INVALID_ARGUMENT

標籤::UNIQUE_ID

版本:3、4

可重複?不

用於在證明中提供唯一 ID。

該值是一個 blob,一個任意長度的位元組數組。

標籤::USAGE_EXPIRE_DATETIME

版本:1、2、3、4

可重複?不

指定用於驗證和解密目的的金鑰到期的日期和時間。此後,任何嘗試使用提供的KeyPurpose::VERIFYKeyPurpose::DECRYPT開始的金鑰都會失敗,並顯示ErrorCode::KEY_EXPIRED

該值是一個 64 位元整數,表示自 1970 年 1 月 1 日以來的毫秒數。

標籤::USER_AUTH_TYPE

版本:1、2、3、4

可重複?不

指定可用於授權此金鑰的使用者驗證器的類型。當請求 Keymaster 使用帶有此標籤的金鑰執行操作時,它會收到一個身份驗證令牌,並且該令牌的authenticator_type欄位需要與標籤中的值相符。例如, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 ,其中ntoh是將網路排序整數轉換為主機排序整數的函數,而auth_type_tag_value是此標記的值。

該值是枚舉值的 32 位元整數位元遮罩:

Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 及更早版本
typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

標籤::USER_SECURE_ID

版本:1、2、3、4

可重複?不

指定金鑰只能在特定的安全用戶身份驗證狀態下使用。該標籤與Tag::NO_AUTH_REQUIRED互斥。

該值是一個 64 位元整數,指定身份驗證策略狀態值,該值需要出現在身份驗證令牌中(以Tag::AUTH_TOKEN開頭)以授權使用金鑰。任何以具有此標記的金鑰開頭但不提供身份驗證令牌或提供不匹配策略狀態值的身份驗證令牌的呼叫都會失敗。

該標籤是可重複的。如果提供的任何值與身份驗證令牌中的任何策略狀態值匹配,則授權使用該金鑰。否則,操作將失敗並顯示ErrorCode::KEY_USER_NOT_AUTHENTICATED

標籤::VENDOR_PATCHLEVEL

版本:4

此標籤指定可以使用金鑰的供應商映像安全性修補程式等級。該標籤永遠不會傳送給金鑰主控 TA,而是由 TA 新增至硬體強制授權清單。任何嘗試使用Tag::VENDOR_PATCHLEVEL值與目前運行的系統補丁等級不同的金鑰都必須導致begin()getKeyCharacteristics()exportKey()傳回ErrorCode::KEY_REQUIRES_UPGRADE 。詳細資訊請參閱upgradeKey()

標記的值是 YYYYMMDD 形式的整數,其中 YYYY 是上次更新的四位數年份,MM 是兩位數月份,DD 是上次更新的兩位數日期。例如,對於上次更新時間為 2018 年 6 月 5 日的 Android 裝置上產生的金鑰,該值將為 20180605。

IKeymasterDevice HAL 必須從系統屬性ro.vendor.build.security_patch讀取當前供應商補丁級別,並在首次加載 HAL 時將其傳遞到安全環境(機制是實現定義的)。在下次啟動之前,安全環境不得接受另一個修補程式等級。

必須由硬體強制執行。