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_AUTH_TYPE指定的身份驗證方法成功對Tag::USER_SECURE_ID指定的用戶進行身份驗證後,可以使用密鑰的時間(以秒為單位)。

標籤::AUTH_TOKEN

版本:1、2、3、4

可重複?不

提供一個身份驗證令牌開始更新完成,以證明需要它的密鑰操作的用戶身份驗證(密鑰具有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 ::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 指定可以使用密鑰的引導映像(內核)安全補丁級別。這個標籤永遠不會發送到 keymaster 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

可重複?不

指定只有引導加載程序可以使用密鑰。

這個標籤是布爾值,所以可能的值為真(如果標籤存在)和假(如果標籤不存在)。

任何嘗試使用來自 Android 系統的Tag::BOOTLOADER_ONLY鍵的嘗試都會失敗,並顯示ErrorCode::INVALID_KEY_BLOB

標籤::CALLER_NONCE

版本:1、2、3、4

可重複?不

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

這個標籤是布爾值,所以可能的值為真(如果標籤存在)和假(如果標籤不存在)。

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

標籤::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指定的那樣。

這個標籤是布爾值,所以可能的值為真(如果標籤存在)和假(如果標籤不存在)。

標籤::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 內存通常是有限的,因此此表可以具有固定的最大大小,並且當表已滿時,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 內存通常是有限的,因此此表可以具有固定的最大大小,並且當表已滿時,Keymaster 可能會使嘗試使用帶有此標記的鍵的操作失敗。該表需要容納至少 32 個正在使用的鍵,並在鍵的最小使用間隔到期時積極地重用表槽。如果由於表已滿而導致操作失敗,Keymaster 將返回ErrorCode::TOO_MANY_OPERATIONS

標籤::NO_AUTH_REQUIRED

版本:1、2、3、4

可重複?不

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

這個標籤是布爾值,所以可能的值為真(如果標籤存在)和假(如果標籤不存在)。

標籤::NONCE

版本:1、2、3、4

可重複?不

為 AES GCM、CBC 或 CTR 加密或解密提供或返回隨機數或初始化向量 (IV)。提供此標籤以在加密和解密操作期間開始。僅當密鑰具有Tag::CALLER_NONCE時才提供開始。如果未提供,Keymaster 將隨機生成適當的 nonce 或 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 中的。如果在硬件強制列表中,則它是永久硬件綁定的,儘管可能存在安全硬件之外的副本。如果在 software-enforces 列表中,密鑰被導入到 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

可重複?不

這個標籤永遠不會發送到 keymaster TA,而是由 TA 添加到硬件強制授權列表中。

標籤的值是 YYYYMM 形式的整數,其中 YYYY 是最後一次更新的四位數年份,MM 是最後一次更新的兩位數月份。例如,對於在 2015 年 12 月最後一次更新的 Android 設備上生成的密鑰,其值為 201512。

補丁級別與當前補丁級別不同的密鑰不可用。嘗試使用此類密鑰會導致begingetKeyCharacteristicsexportKey返回ErrorCode::KEY_REQUIRES_UPGRADE 。有關詳細信息,請參閱版本綁定

標籤::OS_VERSION

版本:2、3、4

可重複?不

這個標籤永遠不會發送到 keymaster 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 塊大小的倍數,則調用完成將失敗並顯示ErrorCode::INVALID_INPUT_LENGTH

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

這個標籤是可重複的。必須在調用begin時指定填充模式。如果指定的模式未獲得密鑰授權,則操作將失敗並顯示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 輪換後設備是否已恢復出廠設置。用於密鑰證明。

這個標籤是布爾值,所以可能的值為真(如果標籤存在)和假(如果標籤不存在)。

標籤::ROLLBACK_RESISTANT

版本:1、2、3、4

可重複?不

表示 key 是抗回滾的,也就是說當被deleteKeydeleteAllKeys刪除時,保證 key 被永久刪除並且不可用。沒有此標籤的密鑰可能會被刪除,然後從備份中恢復。

這個標籤是布爾值,所以可能的值為真(如果標籤存在)和假(如果標籤不存在)。

標籤::ROOT_OF_TRUST

版本:1、2、3、4

可重複?不

指定信任根,驗證引導用於驗證已引導操作系統(如果有)的密鑰。在密鑰特性中,此標籤永遠不會提供給 Keymaster 或從 Keymaster 返回。

標籤::RSA_PUBLIC_EXPONENT

版本:1、2、3、4

可重複?不

指定 RSA 密鑰對的公共指數值。此標記僅與 RSA 密鑰相關,並且對所有 RSA 密鑰都是必需的。

該值是一個滿足 RSA 公共指數要求的 64 位無符號整數。該值必須是素數。 Trustlets 支持值 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

此標記指定可以使用密鑰的供應商映像安全補丁級別。這個標籤永遠不會發送到 keymaster 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 首次加載時將其交付到安全環境(機制由實現定義)。直到下一次引導之後,安全環境才能接受另一個補丁級別。

必須是硬件強制的。