Keymaster 函式

本頁提供詳細資訊，協助 Keymaster 的實作者 硬體抽象層 (HAL)。其中涵蓋 該 API 以及該版本有哪些 Keymaster 版本 說明預設實作方式如果是代碼，請參閱 「Keymaster Tags」頁面。

一般導入指南

下列指南適用於 API 的所有函式。

輸入指標參數

版本：1、2

未用於特定呼叫的輸入指標參數，可能 NULL。呼叫端不需要提供預留位置。 例如，某些鍵類型和模式可能無法使用 開始的 inParams 引數，因此呼叫端可能會 將 inParams 設為 NULL，或提供空白參數 設定。呼叫端也可以提供未使用的參數，而 Keymaster 方法應 完全沒有問題。

如果必要的輸入參數為 NULL，Keymaster 方法應傳回 ErrorCode::UNEXPECTED_NULL_POINTER。

從 Keymaster 3 開始，沒有指標參數。所有參數 會透過值或 const 參照傳遞。

輸出指標參數

版本：1、2

與輸入指標參數類似，未使用的輸出指標參數 可能是 NULL。如果方法需要在輸出中傳回資料 參數是 NULL，它應該會傳回 ErrorCode::OUTPUT_PARAMETER_NULL。

從 Keymaster 3 開始，沒有指標參數。所有參數 會透過值或 const 參照傳遞。

API 濫用

版本：1、2、3

來電者提出請求的方式有很多種，而且這些方法並不合理，或 是詐騙內容，但技術上不算錯誤。Keymaster 的實作 而必須執行這些動作，才能進行診斷或發出診斷要求。使用太小的按鍵 指定不相關的輸入參數、重複使用 IV 或 Nonce 沒有用途 (因此無用) 的金鑰產生方式 並診斷結果省略必要參數、 的規格 無效的必要參數，及類似的錯誤必須被診斷。

應用程式、架構和 Android KeyStore 必須負責 確保對 Keymaster 模組的呼叫合理且實用。

函式

getHardwareFeatures

版本：3

新的 getHardwareFeatures 方法會向用戶端公開 基礎安全硬體的重要特性 此方法不需使用引數，並會傳回四個值，全都是布林值：

  • 如果金鑰儲存在哪個位置，isSecure 會是 true 安全硬體 (TEE 等) 安全保密
  • 如果supportsEllipticCurvetrue 硬體透過 NIST 曲線支援橢圓曲線密碼編譯 (P-224、 P-256、P-384 和 P-521)。
  • 「supportsSymmetricCryptography」將在 true後開始 ，前提是硬體支援對稱密碼編譯 (包括 AES 和 HMAC)。
  • 如果supportsAttestationtrue 硬體支援產生 Keymaster 公開金鑰認證憑證 由在安全環境中插入的金鑰進行簽署。

這個方法可能傳回的唯一錯誤代碼是 ErrorCode:OK。 ErrorCode::KEYMASTER_NOT_CONFIGURED 或其中一個錯誤代碼 表示無法與安全硬體通訊。 

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

設定

版本：2

這個函式是在 Keymaster 2 中推出，並在 Keymaster 中淘汰 3，因為這類資訊可在系統屬性檔案和製造商中找到 都會在啟動期間讀取這些檔案

設定 Keymaster。系統會在裝置開啟後呼叫此方法一次 以及使用前的注意事項用途 KM_TAG_OS_VERSION 和 KM_TAG_OS_PATCHLEVEL 到 keymaster。呼叫此方法前，所有其他方法均會傳回 KM_ERROR_KEYMASTER_NOT_CONFIGURED。此屬性提供的值 方法每次啟動時，Keymaster 只會接受一次。隨後 呼叫會傳回 KM_ERROR_OK，但不會執行任何動作。

如果 Keymaster 實作為安全的硬體和 OS 版本 您提供的修補程式等級值與 硬體啟動載入程式 (如果系統啟動載入程式未提供值)， 這個方法會傳回 KM_ERROR_INVALID_ARGUMENT， 方法會繼續傳回 KM_ERROR_KEYMASTER_NOT_CONFIGURED。

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

addRngEntropy

版本：1、2、3

這個函式在 Keymaster 1 中以 add_rng_entropy 的形式推出 並在 Keymaster 3 中重新命名

將呼叫端提供的熵新增至 Keymaster 1 實作使用的集區 來產生隨機號碼 適用於索引鍵、IV 等

Keymaster 實作作業需要安全混用 這項原則也必須包含 內部產生的資訊熵。 應處理混合，以便擁有完全控制權的攻擊者 addRngEntropy 提供的位元或硬體產生的值 但反之，在預測位元時 從熵池產生的資訊

Keymaster 實作項目：嘗試以 內部集區會假設 addRngEntropy 不包含熵。Keymaster 實作可能會 如果提供超過 2 個，則傳回 ErrorCode::INVALID_INPUT_LENGTH 在單一呼叫中處理資料的 KiB。

generateKey

版本：1、2、3

這個函式在 Keymaster 1 中以 generate_key 的形式推出 並在 Keymaster 3 中重新命名

產生新的加密編譯金鑰，指定相關聯的授權 這些物件會永久繫結至金鑰Keymaster 實作可以 無法以任何方式與授權不一致的方式使用金鑰 都會在產生時指定有關 安全硬體無法強制執行的義務，安全硬體義務僅限於 確保與金鑰相關聯的無法強制執行授權 因此，每次呼叫 getKeyCharacteristics 會傳回原始值。此外，如果模型傳回的特徵 generateKey 會在 硬體強制執行清單及軟體強制執行清單詳情請見 getKeyCharacteristics。

提供給 generateKey 的參數取決於金鑰類型 。本節摘要說明 以及每一種金鑰類型標記：ALGORITHM 來指定類型。

RSA 金鑰

產生 RSA 金鑰須有下列參數。

  • 代碼：KEY_SIZE 會指定公開模數的大小 (以位元為單位)。省略時 此方法會傳回 ErrorCode::UNSUPPORTED_KEY_SIZE。 支援的值為 1024、2048、3072 和 4096。建議值 都是 8 的倍數
  • 標記：RSA_PUBLIC_EXPONENT 會指定 RSA 公開指數值。如果您省略這個屬性， 會傳回 ErrorCode::INVALID_ARGUMENT。 支援的值為 3 和 65537。建議值為 所有質值最多 2^64

產生 RSA 金鑰不需要下列參數，但 建立 RSA 金鑰卻沒有它們會產生無法使用的金鑰。不過， 如果這些參數，generateKey 函式不會傳回錯誤 已省略。

  • Tag::PURPOSE 指定 目的。RSA 金鑰必須支援 可以任意組合。
  • Tag::DIGEST 會指定 可能與新金鑰搭配使用的摘要演算法。導入 不支援所有摘要演算法的金鑰產生作業須接受金鑰產生 內含不支援的摘要的要求。不支援的摘要應為 放在「software-enforced」字串清單。 這是因為金鑰可以與其他摘要搭配使用 都是在軟體中執行接著呼叫硬體來執行 只在 Digest::NONE。
  • Tag::PADDING 指定 可能與新鍵搭配使用的邊框間距模式。導入 不支援所有摘要演算法 PaddingMode::RSA_PSS和PaddingMode::RSA_OAEP 英吋 軟體強制列出的主要特性 (如有不支援) 會指定摘要演算法。

ECDSA 金鑰

只有 Tag::KEY_SIZE 是 產生 ECDSA 金鑰用來選取強化轉換群組。 支援的值為 224、256、384 和 521，代表 分別為 NIST p-224、p-256、p-384 和 p521 曲線。

標記：DIGEST 對實用的 ECDSA 金鑰也須這麼做 但產生的結果並非必要。

AES 金鑰

僅限標記：:KEY_SIZE 產生 AES 金鑰。如果省略，此方法會傳回 ErrorCode::UNSUPPORTED_KEY_SIZE。支援的值如下： 128 和 256，支援 192 位元 AES 金鑰。

下列參數與 AES 金鑰特別相關，但不適用於 來產生這種程式碼

  • Tag::BLOCK_MODE 會指定可以套用的封鎖模式 即可使用新的金鑰
  • Tag::PADDING 會指定可能的邊框間距模式 這只適用於 ECB 和 CBC 模式。

如果已指定 GCM 封鎖模式，請提供 標記：MIN_MAC_LENGTH。 如果省略，這個方法會傳回 ErrorCode::MISSING_MIN_MAC_LENGTH。 該標記的值是 8 到 96 到 128 的倍數。

HMAC 金鑰

產生 HMAC 金鑰時需要下列參數：

  • 代碼：KEY_SIZE 會指定金鑰大小 (以位元為單位)。小於 64 的值 以及非 8 的倍數的值。所有語言 這個 8 的倍數 (從 64 到 512) 也支援。較大的值可以 支援。
  • 標記：MIN_MAC_LENGTH 會指定 可使用這組金鑰產生或驗證的 MAC。這個值是 值為 8 的倍數，且至少應設為 64。
  • 標記：DIGEST 會指定金鑰的摘要演算法。等於 指定一個摘要，否則會傳回 ErrorCode::UNSUPPORTED_DIGEST。如果系統不支援摘要 信託，傳回 ErrorCode::UNSUPPORTED_DIGEST。

主要特色

如果特性引數不是 NULL，generateKey 就會傳回 新產生的鍵特性 硬體強制執行清單及軟體強制執行清單詳情請見 getKeyCharacteristics： 然後列出所具備的特性傳回的特性 包含金鑰產生作業指定的所有參數，但 Tag::APPLICATION_ID 和 標記：APPLICATION_DATA。 如果這些代碼包含在關鍵參數中，就會從 傳回的特徵，因此找不到相關的值 來檢查傳回的鍵 blob。不過，金鑰會經過加密編譯 新增至鍵 blob，如果鍵是在 但使用失敗同樣地 標記：:ROOT_OF_TRUST 是 與金鑰加密，但可能無法在 金鑰建立或匯入作業，而且永遠不會傳回該值。

除了提供的標記以外，信任小程式也會 加入 Tag::功能、 值為 KeyOrigin::GENERATED， 如果金鑰能夠復原

標記：ROLLBACK_RESISTANT。

無法復原

「復原抵禦機制」是指藉由 deleteKey 或 deleteAllKeys，皆由安全硬體保證金鑰 變得不能再使用實作時通常不會復原阻礙 會將產生或匯入的金鑰內容做為鍵 blob 傳回呼叫端， 加密及驗證形式KeyStore 刪除鍵 blob 時，索引鍵為 而是攻擊者，先前曾設法擷取金鑰內容 可能會還原到裝置

如果安全硬體保證刪除金鑰，金鑰可復原 金鑰一經還原即無法還原。這通常是指儲存額外的金鑰 中繼資料儲存在受信任位置，且遭到攻擊者控制。啟用 行動裝置，這項機制通常會重新播放受保護的記憶體 區塊 (RPMB)：因為建立的金鑰數量基本上 且用於復原的信任儲存空間可能會受到限制 但即使在復原抗拒期間，此方法也要成功 無法為新的金鑰提供。在此情況下 標記：ROLLBACK_RESISTANT 不得加入主要特性

getKeyCharacteristics

版本：1、2、3

這個函式是在 Keymaster 1 中導入， get_key_characteristics，並在 Keymaster 3 中重新命名。

傳回與所提供金鑰相關聯的參數和授權。 分為兩組：硬體強制執行和軟體強制執行說明 這裡的原則，都等同 generateKey 和 importKey 傳回的主要特色清單。

如果在產生金鑰時提供 Tag::APPLICATION_ID 同一個值 傳入 clientId 引數中。否則， 方法會傳回 ErrorCode::INVALID_KEY_BLOB。同樣地 如果在產生期間提供 Tag::APPLICATION_DATA 同一個值 傳入 appData 引數中。

此方法傳回的特性完全描述型別 指定金鑰的使用方式

決定指定廣告代碼是否屬於 硬體或軟體強制執行清單的意義是 因此完全採用安全硬體，並且強制執行硬體。否則，使用者 軟體強制執行。下列是有正確分配的代碼清單 可能不清楚：

  • Tag::ALGORITHM、 Tag::KEY_SIZE、 和標記：RSA_PUBLIC_EXPONENT 是該鍵的內建屬性對於受硬體保護的任何金鑰 這些標記會出現在硬體強制執行的清單中。
  • 標記::DIGEST 值 都會放在 硬體支援清單不支援的摘要會列在軟體支援清單中。
  • Tag::PADDING 值 通常會有硬體支援清單 可能是由軟體執行特定的邊框間距模式。 在此情況下，這些廠商會列入軟體強制執行清單。因此 RSA 金鑰如果允許使用 PSS 或 OAEP 填充演算法，會產生摘要演算法 不受安全硬體支援
  • 標記：USER_SECURE_ID 和代碼：USER_AUTH_TYPE 只有在強制執行使用者驗證的情況下，才會強制使用硬體。目的地： 因此 Keymaster Trustlet 和相關驗證作業 同時確保安全無虞，並分享用於簽署及協議的密鑰 HMAC 金鑰 驗證驗證權杖。詳情請參閱 詳情請參閱「驗證」頁面。
  • Tag::ACTIVE_DATETIME 代碼：ORIGINATION_EXPIRE_DATETIME、 和標記::USAGE_EXPIRE_DATETIME標記 必須存取可驗證的正確壁掛時鐘。最安全的硬體 只能存取由不安全 OS 提供的時間資訊 代表標記是由軟體強制執行
  • Tag::表示 為 一律列在硬體繫結金鑰的硬體清單中。它的存在 清單是指較高層判斷金鑰是否受到硬體支援的方式。

匯入金鑰

版本：1、2、3

這個函式在 Keymaster 1 中以 import_key 的形式推出 並在 Keymaster 3 中重新命名

將金鑰內容匯入 Keymaster 硬體。主要定義參數和 處理輸出特性的方式與 generateKey 相同。 例外：

  • Tag::KEY_SIZE 和 標記：RSA_PUBLIC_EXPONENT (僅適用於 RSA 金鑰) 輸入參數並非必要。如未提供 Trustlet 會根據提供的金鑰內容產生值，並將 建議您根據主要特性選擇適當的標記和值如果參數 並根據金鑰內容驗證這些憑證在 這個方法會傳回 ErrorCode::IMPORT_PARAMETER_MISMATCH。
  • 傳回的 Tag::表示 會包含 值與 KeyOrigin::IMPORTED 相同。

<匯出鍵>

版本：1、2、3

這個函式在 Keymaster 1 中以 export_key 的形式推出 並在 Keymaster 3 中重新命名

從 Keymaster RSA 或 EC 金鑰組匯出公開金鑰。

如果在產生金鑰或產生金鑰時提供 Tag::APPLICATION_ID 參數，相同的值會在 clientId 引數。如果沒有，則此方法會傳回 ErrorCode::INVALID_KEY_BLOB。同樣地， Tag::APPLICATION_DATA 是在產生或匯入期間提供的同一個值， 傳入 appData 引數中。

刪除鍵

版本：1、2、3

這個函式在 Keymaster 1 中以 delete_key 的形式推出 並在 Keymaster 3 中重新命名

刪除提供的金鑰。此為選擇性方法， 是由提供復原抗力的 Keymaster 模組實作。

刪除所有金鑰

版本：1、2、3

這個函式在 Keymaster 1 中以 delete_all_keys 的形式推出 並在 Keymaster 3 中重新命名

刪除所有金鑰。這種方法並非必要，而且只有 。

destroyAttestationId

版本：3

destroyAttestationIds() 方法用於永久 停用新的設定 (選擇性做法，但極力建議使用) ID 認證 而不是每個特徵的分數如果 TEE 無法確保永久 ID 認證 呼叫此方法後，就無法使用 ID 認證 此時這個方法不會執行任何動作 會傳回 ErrorCode::UNIMPLEMENTED。如果 ID 認證為 您需要導入這個方法，而且必須永久停用 。此方法可呼叫任意數量的 次。如果 ID 認證已永久停用，此方法 不會傳回 ErrorCode::OK。

這個方法可能傳回的唯一錯誤代碼 ErrorCode::UNIMPLEMENTED (如果不支援 ID 認證)， ErrorCode:OK、ErrorCode::KEYMASTER_NOT_CONFIGURED或 其中一個錯誤代碼，表示無法與安全連線 硬體

開始

版本：1、2、3

使用指定金鑰，針對指定的金鑰開始進行加密編譯作業 並傳回 作業控制代碼與 update 和 finish 搭配使用以完成作業。作業控點是 也用作「挑戰」權杖化作業，並使用 則包含在 Deployment 的 challenge 欄位中 驗證權杖

Keymaster 實作至少支援 16 個並行作業 作業。KeyStore 最多使用 15 個，因此只有 1 個要用於密碼 加密。當 KeyStore 有 15 項作業正在執行時 (begin 尚未呼叫 finish 或 abort 呼叫) 且收到開始進行 16 的要求時， 對最近最少使用的作業執行 abort，以減少 呼叫 begin 以啟動 新要求的作業。

如果標記：APPLICATION_ID 或 Tag::APPLICATION_DATA 就在金鑰產生或匯入期間，對 begin 的呼叫包含這些 具有 inParams 引數原本指定值的標記 加入這個方法

強制執行授權

在此方法中， 將實作方式放在「硬體強制執行」狀態 並非公開金鑰作業。公開金鑰 作業，亦即 KeyPurpose::ENCRYPT 和 KeyPurpose::VERIFY 與 RSA 或 EC 金鑰一樣，即使授權成功， 則不符合這些條件。

  • Tag::PURPOSE：目的 begin() 呼叫中指定的其中一個用途必須與 金鑰授權中，除非所要求的作業是公開金鑰 作業。如果指定的用途不符，且作業並未 公開金鑰作業，begin 會傳回 ErrorCode::UNSUPPORTED_PURPOSE。公開金鑰作業 非對稱式加密或驗證作業
  • 標記：ACTIVE_DATETIME 只有在可提供信任的世界標準時間來源時，才能強制執行。如果 當前日期和時間早於標記值，這個方法會傳回 ErrorCode::KEY_NOT_YET_VALID。
  • 代碼：ORIGINATION_EXPIRE_DATETIME 只有在可提供信任的世界標準時間來源時，才能強制執行。如果 目前的日期和時間晚於標記值，而用途為 KeyPurpose::ENCRYPT 或 KeyPurpose::SIGN，方法 會傳回 ErrorCode::KEY_EXPIRED。
  • 標記：USAGE_EXPIRE_DATETIME 只有在可提供信任的世界標準時間來源時，才能強制執行。如果 目前的日期和時間晚於標記值，而用途為 KeyPurpose::DECRYPT 或 KeyPurpose::VERIFY，方法 會傳回 ErrorCode::KEY_EXPIRED。
  • 標記：MIN_SECONDS_BETWEEN_OPS 會與信任的相對計時器進行比較 。如果上次使用時間加上標記值小於目前時間， 此方法會傳回 ErrorCode::KEY_RATE_LIMIT_EXCEEDED。詳情請參閱 代碼說明 ，瞭解重要的實作細節
  • 標記：MAX_USES_PER_BOOT 會與追蹤金鑰使用情況的安全計數器進行比較 。如果先前使用的計數超出標記值， 方法會傳回 ErrorCode::KEY_MAX_OPS_EXCEEDED。
  • 標記：USER_SECURE_ID 只有在金鑰具備 Tag::AUTH_TIMEOUT。 如果金鑰同時包含 Tag::AUTH_TOKEN 欄 inParams。為確保驗證權杖生效，請符合下列所有條件 必須是 true：

    如果不符合上述任一條件，這個方法會傳回 ErrorCode::KEY_USER_NOT_AUTHENTICATED。

  • 代碼：CALLER_NONCE 可讓呼叫端指定 Nonce 或初始化向量 (IV)。如果索引鍵 沒有這個標記，但呼叫端提供的 Tag::NONCE 這項功能，但 會傳回 ErrorCode::CALLER_NONCE_PROHIBITED。
  • 代碼：BOOTLOADER_ONLY 會指定只有系統啟動載入程式可以使用金鑰。如果這個方法 系統啟動載入程式執行完畢後，會以僅限系統啟動載入程式的金鑰呼叫。 它會傳回 ErrorCode::INVALID_KEY_BLOB。

RSA 金鑰

所有 RSA 金鑰作業在 inParams 中都只會指定一個邊框間距模式。 如果未指定或多次指定，這個方法會傳回 ErrorCode::UNSUPPORTED_PADDING_MODE。

RSA 簽署和驗證作業需要摘要和 RSA 加密 以及解密作業和解密作業在這種情況下，呼叫端 只會在 inParams 中指定一個摘要。如果未指定或指定 超過一次，此方法會傳回 ErrorCode::UNSUPPORTED_DIGEST。

私密金鑰作業 (KeyPurpose::DECYPT 和 KeyPurpose::SIGN) 需要摘要和填充機制 也就是說， 必須包含指定值如果不是，此方法會傳回 ErrorCode::INCOMPATIBLE_DIGEST 或 ErrorCode::INCOMPATIBLE_PADDING (如適用)。公開金鑰作業 (KeyPurpose::ENCRYPT 和 KeyPurpose::VERIFY) 允許使用 未經授權摘要或填充字詞。

除了 PaddingMode::NONE 以外，所有 RSA 邊框間距模式都會 但僅適用於某些用途具體而言 「PaddingMode::RSA_PKCS1_1_5_SIGN」和「PaddingMode::RSA_PSS」 僅支援簽署和驗證，而 PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT 和 PaddingMode::RSA_OAEP 僅支援加密與解密。 如果ErrorCode::UNSUPPORTED_PADDING_MODE 指定的模式不支援指定用途。

邊框間距模式和摘要之間有一些重要的互動關係：

  • PaddingMode::NONE 表示「原始」RSA 作業為 執行任務如果簽署或驗證，Digest::NONE 就會 提供給摘要無填充加密或 解密。
  • PaddingMode::RSA_PKCS1_1_5_SIGN 填充需要摘要。 摘要可能是 Digest::NONE，在這種情況下，Keymaster 實作無法建立正確的 PKCS#1 v1.5 簽章結構，因為 就無法新增 DigestInfo 結構。相反地 建構 0x00 || 0x01 || PS || 0x00 || M，其中 M 是 提供的訊息，PS 為邊框間距字串。RSA 金鑰的大小 至少比訊息大 11 個位元組，否則此方法會傳回 ErrorCode::INVALID_INPUT_LENGTH。
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT 邊框間距不需要摘要。
  • PaddingMode::RSA_PSS 填充需要摘要， Digest::NONE。如果指定 Digest::NONE， 方法會傳回 ErrorCode::INCOMPATIBLE_DIGEST。此外， RSA 金鑰的大小至少比輸出值多 2 + D 個位元組 摘要的大小，其中 D 是摘要的大小，以位元組為單位。其他情況 此方法會傳回 ErrorCode::INCOMPATIBLE_DIGEST。鹽大小 D。
  • PaddingMode::RSA_OAEP 填充需要摘要， Digest::NONE。如果指定 Digest::NONE， 方法會傳回 ErrorCode::INCOMPATIBLE_DIGEST。

EC 金鑰

EC 鍵作業只會在 inParams 中指定一種邊框間距模式。 如果未指定或多次指定，這個方法 會傳回 ErrorCode::UNSUPPORTED_PADDING_MODE。

需授權使用私密金鑰作業 (KeyPurpose::SIGN) 不會產生摘要和填充值 這意味著 必須包含指定值如果沒有，則傳回 ErrorCode::INCOMPATIBLE_DIGEST。公開金鑰作業 系統允許 (KeyPurpose::VERIFY) 取得未經授權的摘要或填充字元。

AES 金鑰

AES 金鑰作業僅指定一個區塊模式和一種填充模式 在「inParams」中。如果未指定或未指定任何值 則會傳回 ErrorCode::UNSUPPORTED_BLOCK_MODE 或 ErrorCode::UNSUPPORTED_PADDING_MODE。指定的模式必須 金鑰授權，否則該方法會傳回 ErrorCode::INCOMPATIBLE_BLOCK_MODE或 ErrorCode::INCOMPATIBLE_PADDING_MODE。

如果封鎖模式為 BlockMode::GCM，inParams 會指定 Tag::MAC_LENGTH，而 指定的值是 8 的倍數 (不大於 128) 或小於Tag::MIN_MAC_LENGTH 金鑰授權。適用於 MAC 長度大於 128 或非倍數的 8，傳回 ErrorCode::UNSUPPORTED_MAC_LENGTH。小於值 超過該鍵的長度下限，就會傳回 ErrorCode::INVALID_MAC_LENGTH。

如果封鎖模式為 BlockMode::GCM 或 BlockMode::CTR， 指定的邊框間距模式必須是 PaddingMode::NONE。 如果是 BlockMode::ECB 或 BlockMode::CBC，模式可能是 PaddingMode::NONE或PaddingMode::PKCS7。如果邊框間距模式 不符合這些條件，請傳回 ErrorCode::INCOMPATIBLE_PADDING_MODE。

如果封鎖模式為 BlockMode::CBC、BlockMode::CTR， 或 BlockMode::GCM，就需要初始化向量或 Nonce。 大多數情況下，呼叫端不應提供 IV 或 Nonce。在此情況下， Keymaster 實作會產生隨機 IV 或 Nonce，並透過以下方式傳回： Tag::NONCE (在 outParams 中)。 CBC 和點閱率 IV 是 16 個位元組。GCM Nonce 為 12 個位元組。如果索引鍵 授權包含 Tag::CALLER_NONCE、 那麼來電者可能會提供 標記：NONCE 位置：inParams。如果系統在 代碼：CALLER_NONCE 未獲授權，請傳回 ErrorCode::CALLER_NONCE_PROHIBITED。 如果在 代碼：CALLER_NONCE 取得授權並隨機產生 IV/nonce

HMAC 金鑰

HMAC 金鑰作業在 inParams 中指定 Tag::MAC_LENGTH。 指定值必須是不大於 8 的倍數 摘要長度或小於 Tag::MIN_MAC_LENGTH 的值 驗證憑證如果 MAC 長度大於摘要長度，或是 非 8 的倍數，會傳回 ErrorCode::UNSUPPORTED_MAC_LENGTH。 如果值小於該鍵的長度下限，則傳回以下值： ErrorCode::INVALID_MAC_LENGTH。

更新

版本：1、2、3

提供從「開始」開始的進行中作業中要處理的資料。 這項作業是由 operationHandle 參數指定。

為了讓緩衝區處理更有彈性，建議您導入這個方法 可選擇採用比我們提供的資料量更少。來電者是 負責在後續呼叫中以迴圈方式提供其他資料。 所耗用的輸入量會透過 inputConsumed 參數傳回。 實作項目一律至少會使用一個位元組，除非 作業無法接受更多；如果提供超過 0 個位元組且 0 位元組，呼叫端會將這個錯誤視為錯誤並取消作業。

導入作業還可選擇要傳回多少資料，因為 更新。這項設定僅適用於加密和解密作業，因為 簽署和驗證作業在完成前不會傳回任何資料。 請盡早傳回資料，不要進行緩衝處理。

處理錯誤

如果這個方法傳回 ErrorCode::OK 以外的錯誤代碼， 作業已取消，且作業控制代碼已失效。不限 透過這個方法 finish 或 abort， 會傳回 ErrorCode::INVALID_OPERATION_HANDLE。

強制執行授權

系統主要是在「開始」強制執行金鑰授權。 例外狀況如下：

在此情況下，金鑰需要每次作業的授權，而且更新 方法會收到 Tag::AUTH_TOKEN inParams 引數中。HMAC 驗證憑證是否有效且其中包含 相符的安全使用者 ID，與金鑰的 代碼：USER_AUTH_TYPE、 ，其中包含目前作業的處理常式， 挑戰欄位如果不符合這些條件，則傳回以下值： ErrorCode::KEY_USER_NOT_AUTHENTICATED。

呼叫端會提供驗證權杖給每個 update 和 finish。實作項目只需視需要驗證一次權杖。

RSA 金鑰

使用 Digest::NONE 進行簽署和驗證程序， 這個方法可讓整個區塊在單一區塊中簽署或驗證 更新。不可只使用區塊的一部分。不過，如果呼叫端 選擇一次提供多個更新資料，此方法接受。 如果呼叫端提供更多要簽署的資料 ( 資料量超過 RSA 金鑰大小)，傳回 ErrorCode::INVALID_INPUT_LENGTH。

ECDSA 金鑰

使用 Digest::NONE 進行簽署和驗證程序， 這個方法可讓整個區塊在單一區塊中簽署或驗證 更新。這個方法可能無法只使用部分區塊。

但是，如果呼叫端選擇在多次更新中提供資料， 這個方法接受。如果呼叫端提供更多要簽署的資料 超出可用範圍，則會在不顯示的情況下截斷資料。(這與 處理類似 RSA 作業中提供的過量資料。原因如下 與舊版用戶端相容)。

AES 金鑰

AES GCM 模式支援「關聯驗證資料」透過 代碼：ASSOCIATED_DATA 在 inParams 引數中放置標記。 可在重複呼叫中提供相關聯的資料 (如果 資料過大，無法在單一區塊中傳送)，但一律會在資料前方 加密或解密。更新通話可能會同時收到兩個相關聯的資料 以及用於加密/解密的資料，但後續的更新 資料。呼叫端在通話後為更新呼叫提供相關資料 包含要加密/解密的資料，會傳回 ErrorCode::INVALID_TAG。

如果是 GCM 加密，標記會由以下老師附加到密文 finish。解密期間 已提供給最後一個位元組的資料：Tag::MAC_LENGTH 位元組 更新呼叫就是代碼從指定的叫用中 update 無法得知是否為上次叫用。 其後會處理所有標記資料 (但標記長度除外)，並緩衝可能的標記資料 期間。

完成

版本：1、2、3

完成執行中的作業是從「begin」開始， 處理所有由 Google 所提供 update。

此方法是在作業中呼叫的最後一個項目，因此 就會傳回「已處理的資料」

無論作業是否成功完成或傳回錯誤，此方法都會完成 因而使提供的作業控制代碼失效。不限 日後使用帳號代碼時，這個方法或 update 或 abort，會傳回 ErrorCode::INVALID_OPERATION_HANDLE。

簽署作業會傳回簽章做為輸出內容。驗證作業 接受 signature 參數中的簽章，而不會傳回任何輸出內容。

強制執行授權

系統主要是在以下國家/地區強制執行金鑰授權： begin例外狀況如下：

在此情況下，金鑰需要每次作業的授權，而且更新 方法會收到 Tag::AUTH_TOKEN inParams 引數中。HMAC 驗證憑證 有效，而且包含相符的安全使用者 ID，且與金鑰的 Tag::USER_AUTH_TYPE 和 包含目前作業在 挑戰欄位如果不符合這些條件，則傳回以下值： ErrorCode::KEY_USER_NOT_AUTHENTICATED。

呼叫端會提供驗證權杖給每一次呼叫 update 和 finish。 實作項目只需視需要驗證一次權杖。

RSA 金鑰

視邊框間距模式而定，其他需求條件如下：

  • PaddingMode::NONE。對於無填充的簽署與加密作業， 如果提供的資料比此鍵短，資料就會填補 簽署/加密前，都建議使用左側欄位如果資料的長度與鍵相同 但數值越大，就會傳回 ErrorCode::INVALID_ARGUMENT。適用對象 驗證和解密作業時 做為鍵否則，則傳回 ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS。對於 PSS 填充的簽名作業， PSS 鹽是訊息摘要及隨機產生的大小。 使用 Tag::DIGEST 指定的摘要 (位於開始上的inputParams內) 會作為 PSS 摘要 演算法和 MGF1 摘要演算法。
  • PaddingMode::RSA_OAEP。這個摘要是以 Tag::DIGEST 英寸 系統會使用「begin」上的 inputParams 做為 OAEP 摘要演算法和 SHA1 做為 MGF1 摘要演算法。

ECDSA 金鑰

如果提供的未填充簽署或驗證資料過長，請截斷 基礎架構

AES 金鑰

其他條件會因封鎖模式而異：

  • BlockMode::ECB 或 BlockMode::CBC。 如果邊框間距為 PaddingMode::NONE，而 資料長度不是 AES 區塊大小的倍數，傳回 ErrorCode::INVALID_INPUT_LENGTH。如果邊框間距為 PaddingMode::PKCS7，根據 PKCS#7 規格填充資料。 請注意，PKCS#7 建議新增額外的邊框間距區塊 如果資料是區塊長度的倍數
  • BlockMode::GCM。加密後 (處理後) 所有明文、計算 (標記：MAC_LENGTH 個位元組) 並附加至傳回的密文中在解密過程中 最後一個 Tag::MAC_LENGTH 個位元組如果代碼驗證失敗，請返回 ErrorCode::VERIFICATION_FAILED。

取消

版本：1、2、3

取消進行中的作業。通話中止後，返回 ErrorCode::INVALID_OPERATION_HANDLE： 將所提供的作業控制代碼後續用於 update， 完成或取消。

get_supported_algorithms

版本：1

傳回 Keymaster 硬體支援的演算法清單 。軟體實作傳回空白清單。混合 執行會傳回一個清單，其中只列出 硬體支援模式

Keymaster 1 實作支援 RSA、EC、AES 和 HMAC。

get_supported_block_modes

版本：1

傳回 Keymaster 硬體支援的 AES 區塊模式清單 特定演算法和用途的實作項目。

對於 RSA、EC 和 HMAC (未封鎖加密機制)，這個方法會傳回 空白清單。無效用途會導致方法 傳回 ErrorCode::INVALID_PURPOSE。

Keymaster 1 實作支援 AES 的 ECB、CBC、CTR 和 GCM 加密與解密

get_supported_padding_modes

版本：1

傳回 Keymaster 硬體支援的邊框間距模式清單 特定演算法和用途的實作項目。

HMAC 和 EC 沒有邊框間距概念，因此這個方法會傳回空白清單 。無效用途會導致方法傳回 ErrorCode::INVALID_PURPOSE。

對於 RSA，Keymaster 1 實作支援：

  • 未填充加密、解密、簽署和驗證。未填充用 如果訊息短於公用模數，則加密與簽署 實作項目就必須在空白的情況下加上 0。針對未填充的解密和 驗證，輸入長度必須與公開模數大小相符。
  • PKCS#1 v1.5 加密與簽署填充模式
  • 鹽長度至少為 20 的 PSS
  • 睡眠

針對 ECB 和 CBC 模式下的 AES，Keymaster 1 實作支援否 邊框間距和 PKCS#7 邊框間距。點閱率和 GCM 模式不支援邊框間距。

get_supported_digests

版本：1

傳回 Keymaster 硬體支援的摘要模式清單 特定演算法和用途的實作項目。

不支援 AES 模式或需要摘要，因此此方法會傳回空白 。

Keymaster 1 實作項目可實作已定義的子集 摘要。實作項目提供 SHA-256，並提供 MD5、SHA1、SHA-224、 SHA-256、SHA384 和 SHA512 (完整的定義摘要)。

get_supported_import_formats

版本：1

傳回 Keymaster 硬體支援的匯入格式清單 特定演算法的實作。

Keymaster 1 實作支援 PKCS#8 格式 (不含密碼) 保護) 及支援匯入 RSA 和 EC 金鑰組，並支援從 RAW 檔案匯入 AES 和 HMAC 金鑰內容。

get_supported_export_formats

版本：1

傳回 Keymaster 硬體支援的匯出格式清單 特定演算法的實作。

Keymaster1 實作支援 X.509 格式匯出 RSA， EC 公開金鑰。系統不支援匯出私密金鑰或非對稱金鑰。

歷史函式

Keymaster 0

下列函式屬於原始 Keymaster 0 的定義。他們 都位於 Keymaster 1 struct keymaster1_device_t 中。不過在 Keymaster 中 1.0 未實作，且函式指標設為空值。

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Keymaster 1

下列函式屬於 Keymaster 1 的定義，但 已在 Keymaster 2 和上述 Keymaster 0 函式中移除。

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Keymaster 2

下列函式屬於 Keymaster 2 定義， 已在 Keymaster 3 和上述 Keymaster 1 函式中移除。

  • configure