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 関数のページをご覧ください。

Tag::ACTIVE_DATETIME

バージョン: 1、2、3、4

繰り返し: 不可

鍵が有効になる日時を指定します。この日時より前に鍵を使用しようとすると、ErrorCode::KEY_NOT_YET_VALID で失敗します。

値は、1970 年 1 月 1 日からのミリ秒数を表す 64 ビットの整数です。

Tag::ALGORITHM

バージョン: 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;

Tag::ALL_APPLICATIONS

バージョン: 1、2、3、4

繰り返し: 不可

将来の使用のために予約されています。

Tag::ALLOW_WHILE_ON_BODY

バージョン: 2、3、4

繰り返し: 不可

このタグは、ボディセンサー付きの Android Wear デバイスにのみ適用されます。現時点では、TEE がボディセンサーへのセキュア アクセスを提供できることも、ボディセンサーが高度に安全であることも想定されていません。そのため、このタグは単にソフトウェアで適用される機能であると想定されています。

Tag::ALL_USERS

バージョン: 3、4

繰り返し: 不可

将来の使用のために予約されています。

Tag::APPLICATION_DATA

バージョン: 1、2、3、4

繰り返し: 不可

このタグは、generateKey または importKey に渡された場合、鍵の使用時に常に必要となるデータを指定します。特に、exportKey と getKeyCharacteristics の呼び出しは clientId パラメータに同じ値を提供する必要があり、begin の呼び出しはこのタグおよび同じ関連データを inParams セットの一部として提供する必要があります。正しいデータが指定されなかった場合、関数は ErrorCode::INVALID_KEY_BLOB を返します。

このタグのコンテンツは暗号として鍵にバインドされます。つまり、セキュア環境のシークレットすべてにアクセスできるがタグコンテンツにはアクセスできない攻撃者が、タグコンテンツへのブルート フォース攻撃なしでは鍵を復号できないようにする必要があります。ブルート フォース攻撃に対しては、十分に高いエントロピーを持つコンテンツをアプリで指定することで、タグコンテンツを保護できます。

値は blob で、任意の長さのバイト配列です。

Tag::APPLICATION_ID

バージョン: 1、2、3、4

繰り返し: 不可

このタグは、generateKey または importKey に渡された場合、鍵の使用時に常に必要となるデータを指定します。特に、exportKey と getKeyCharacteristics の呼び出しは clientId パラメータに同じ値を提供する必要があり、begin の呼び出しはこのタグおよび同じ関連データを inParams セットの一部として提供する必要があります。正しいデータが指定されなかった場合、関数は ErrorCode::INVALID_KEY_BLOB を返します。

このタグのコンテンツは暗号として鍵にバインドされます。つまり、セキュア環境のシークレットすべてにアクセスできるがタグコンテンツにアクセスできない攻撃者が、（タグコンテンツへのブルート フォース攻撃なしでは）鍵を復号できないことを意味します。

値は blob で、任意の長さのバイト配列です。

Tag::ASSOCIATED_DATA

バージョン: 1、2、3、4

繰り返し: 不可

AES-GCM 暗号化または復号に「関連データ」を提供します。このタグは update に渡され、暗号化 / 復号されないが GCM タグの計算で使用されるデータを指定します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_APPLICATION_ID

バージョン: 3、4

繰り返し: 不可

キー構成証明を開始したアプリのセットを識別するために使用されます。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_CHALLENGE

バージョン: 3、4

繰り返し: 不可

構成証明でチャレンジを提供するために使用されます。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_BRAND

バージョン: 3、4

繰り返し: 不可

Android の Build.BRAND から返されるデバイスのブランド名を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_DEVICE

バージョン: 3、4

繰り返し: 不可

Android の Build.DEVICE から返されるデバイスのデバイス名を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_IMEI

バージョン: 3、4

繰り返し: 可能

デバイス上のすべての無線通信の IMEI を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_MANUFACTURER

バージョン: 3、4

繰り返し: 不可

Android の Build.MANUFACTURER から返されるデバイスのメーカー名を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_MEID

バージョン: 3、4

繰り返し: 可能

デバイス上のすべての無線通信の MEID を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_MODEL

バージョン: 3、4

繰り返し: 不可

Android の Build.MODEL から返されるデバイスのモデル名を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_PRODUCT

バージョン: 3、4

繰り返し: 不可

Android の Build.PRODUCT から返されるデバイスの製品名を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::ATTESTATION_ID_SERIAL

バージョン: 3、4

繰り返し: 不可

デバイスのシリアル番号を提供します。このフィールドは、デバイスの識別子の構成証明をリクエストする場合にのみ設定されます。

デバイスが ID 構成証明をサポートしていない場合（または以前 destroyAttestationIds() が呼び出されてデバイスが ID を証明できなくなった場合）、このタグを含むキー構成証明リクエストは ErrorCode::CANNOT_ATTEST_IDS で失敗します。

値は blob で、任意の長さのバイト配列です。

Tag::AUTH_TIMEOUT

バージョン: 1、2、3、4

繰り返し: 不可

認証後に鍵の使用が承認される秒数を指定します。Tag::USER_SECURE_ID が存在し、このタグが存在しない場合、鍵を使用するたびに認証が必要になります（オペレーションごとの認証フローの詳細については、begin をご覧ください）。

値は 32 ビットの整数です。Tag::USER_AUTH_TYPE で指定された認証方法で、Tag::USER_SECURE_ID で指定されたユーザーの認証に成功した後、鍵を使用できる時間を秒数で指定します。

Tag::AUTH_TOKEN

バージョン: 1、2、3、4

繰り返し: 不可

認証トークンを必要とする鍵オペレーションに対してユーザー認証の証明の begin、update、または finish を行う認証トークンを提供します（鍵は Tag::USER_SECURE_ID を持ちます）。

値は blob で、hw_auth_token_t 構造を含みます。

Tag::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;

このタグは、指定された条件で鍵が使用可能になることを要求するために、鍵の生成時に指定できます。generateKey と getKeyCharacteristics の鍵特性とともに返される必要があります。呼び出し元が Tag::BLOB_USAGE_REQUIREMENTS の値を KeyBlobUsageRequirements::STANDALONE に指定した場合、Trustlet はファイル システムのサポートなしで使用できる鍵 blob を返します。ディスクが暗号化され、Keymaster 鍵を使用して復号するまでファイル システムを使用できないデバイスの場合、このタグは必須です。

Tag::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 鍵オペレーションの場合に、begin の additionalParams 引数でモードを指定します。指定されたモードが鍵に関連付けられたモードでない場合、オペレーションは ErrorCode::INCOMPATIBLE_BLOCK_MODE で失敗します。

Tag::BOOT_PATCHLEVEL

バージョン: 4

Tag::BOOT_PATCHLEVEL は、鍵を使用できるブートイメージ（カーネル）のセキュリティ パッチレベルを指定します。このタグは Keymaster TA に送信されることはありませんが、TA によってハードウェアで適用する承認リストに追加されます。Tag::BOOT_PATCHLEVEL の値が現在実行中のシステム パッチレベルと異なる鍵を使用しようとすると、begin()、getKeyCharacteristics()、または exportKey() は ErrorCode::KEY_REQUIRES_UPGRADE を返します。詳しくは、upgradeKey() をご覧ください。

タグの値は YYYYMMDD 形式の整数です。YYYY は最終更新日付の 4 桁の年、MM は 2 桁の月、DD は 2 桁の日です。たとえば、Android デバイスで生成された鍵が 2018 年 6 月 5 日に最後に更新された場合、値は 20180605 になります。日付が不明の場合は、00 に置き換えることができます。

ブートローダーは、起動のたびにブートイメージのパッチレベルをセキュア環境に提供する必要があります（メカニズムは実装で定義します）。

ハードウェアで適用する必要があります。

Tag::BOOTLOADER_ONLY

バージョン: 1、2、3、4

繰り返し: 不可

ブートローダーのみが鍵を使用できることを指定します。

このタグはブール値であり、指定可能な値は true（タグが存在する場合）または false（タグが存在しない場合）です。

Android システムから Tag::BOOTLOADER_ONLY を持つ鍵を使用しようとすると、ErrorCode::INVALID_KEY_BLOB で失敗します。

Tag::CALLER_NONCE

バージョン: 1、2、3、4

繰り返し: 不可

ノンスを必要とするオペレーションに呼び出し元がノンスを提供できることを指定します。

このタグはブール値であり、指定可能な値は true（タグが存在する場合）または false（タグが存在しない場合）です。

このタグは AES 鍵でのみ使用され、CBC、CTR、GCM のブロックモードにのみ関連性があります。タグが存在しない場合、実装は、Tag::NONCE を begin に渡すオペレーションを ErrorCode::CALLER_NONCE_PROHIBITED で拒否する必要があります。

Tag::CREATION_DATETIME

バージョン: 1、2、3、4

繰り返し: 不可

鍵が作成された日時を 1970 年 1 月 1 日からのミリ秒数で指定します。このタグは省略可能で、情報提供のみを目的とします。

Tag::DIGEST

バージョン: 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;

このタグは繰り返し可能です。署名オペレーションと検証オペレーションの場合に、begin の additionalParams 引数でダイジェストを指定します。 指定されたダイジェストが鍵に関連付けられたダイジェストでない場合、オペレーションは ErrorCode::INCOMPATIBLE_DIGEST で失敗します。

Tag::EC_CURVE

バージョン: 2、3、4

繰り返し: 不可

Keymaster 1 では、EC 鍵に使用される曲線は、指定された鍵のサイズから推測されていました。Keymaster 2 では、柔軟性を高めるために、曲線を明示的に指定する方法が導入されました。EC 鍵生成リクエストに、Tag::EC_CURVE と Tag::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 を返します。

Tag::INCLUDE_UNIQUE_ID

バージョン: 2、3、4

繰り返し: 不可

このタグは鍵の生成時に指定され、生成された鍵の構成証明書に、時間制限があるアプリスコープのデバイス固有 ID（Tag::UNIQUE_ID で指定されます）が含まれている必要があることを示します。

このタグはブール値であり、指定可能な値は true（タグが存在する場合）または false（タグが存在しない場合）です。

Tag::KEY_SIZE

バージョン: 1、2、3、4

繰り返し: 不可

鍵のアルゴリズムに応じた標準の方法で測定される鍵のサイズをビット数で指定します。たとえば、RSA 鍵の場合、Tag::KEY_SIZE には公開モジュラスのサイズを指定します。AES 鍵の場合は、シークレット鍵マテリアルの長さを指定します。

Tag::MAC_LENGTH

バージョン: 1、2、3、4

繰り返し: 不可

要求される MAC または GCM 承認タグの長さをビット数で指定します。

値は、ビット数で表した MAC 長です。8 の倍数で、鍵に関連付けられた Tag::MIN_MAC_LENGTH の値以上であることが必要です。

Tag::MAX_USES_PER_BOOT

バージョン: 1、2、3、4

繰り返し: 不可

システムが再起動されてから次に再起動されるまでの間に鍵を使用できる最大回数を指定します。これは、鍵の使用レートを制限するメカニズムの 1 つです。

値は、起動ごとの使用回数を表す 32 ビットの整数です。

このタグを持つ鍵がオペレーションで使用された場合、begin 呼び出しの際に、鍵に関連付けられたカウンタがインクリメントされます。鍵カウンタがこの値を超えた場合、デバイスが再起動されるまで、鍵を使用しようとすると ErrorCode::MAX_OPS_EXCEEDED で失敗します。このタグを持つ鍵の使用回数カウンタをテーブルに記録するのは Trustlet です。Keymaster のメモリはサイズが限定されていることが多く、このテーブルの最大サイズが固定されてしまうことがあります。その場合、このテーブルがいっぱいになると、Keymaster はこのタグの付いた鍵を使用するオペレーションを失敗させる可能性があります。テーブルは少なくとも 16 個の鍵を格納できることが必要です。 テーブルがいっぱいになったためにオペレーションが失敗すると、Keymaster は ErrorCode::TOO_MANY_OPERATIONS を返します。

Tag::MIN_MAC_LENGTH

バージョン: 1、2、3、4

繰り返し: 不可

このタグは、GCM モードをサポートする HMAC 鍵と AES 鍵に対してこの鍵で要求または検証できる最小 MAC 長を指定します。

この値は、ビット数で表した最小 MAC 長です。8 の倍数です。HMAC 鍵の場合、値は 64 以上です。GCM 鍵の場合、値は 96 以上 128 以下です。

Tag::MIN_SECONDS_BETWEEN_OPS

バージョン: 1、2、3、4

繰り返し: 不可

鍵を使用するオペレーションから、鍵を使用する次のオペレーションまでの最小時間を指定します。このタグは、無制限の使用が総当たり攻撃を可能にするような状況で、鍵の使用レートを制限するために使用できます。

値は、許可されたオペレーション間の経過時間の秒数を表す 32 ビットの整数です。

このタグを持つ鍵がオペレーションで使用された場合、finish または abort の呼び出しの際にタイマーがカウントを開始します。Tag::MIN_SECONDS_BETWEEN_OPS で指定された間隔が経過したことをタイマーが示す前に受信された begin の呼び出しは、ErrorCode::KEY_RATE_LIMIT_EXCEEDED で失敗します。このタグを持つ鍵の使用回数カウンタをテーブルに記録するのは Trustlet です。Keymaster のメモリはサイズが限定されていることが多く、このテーブルの最大サイズが固定されてしまうことがあります。その場合、このテーブルがいっぱいになると、Keymaster はこのタグの付いた鍵を使用するオペレーションを失敗させる可能性があります。テーブルは少なくとも 32 個の使用中の鍵を格納し、鍵の使用間隔の最小時間が経過したら積極的にテーブル スロットを再利用する必要があります。テーブルがいっぱいになったためにオペレーションが失敗すると、Keymaster は ErrorCode::TOO_MANY_OPERATIONS を返します。

Tag::NO_AUTH_REQUIRED

バージョン: 1、2、3、4

繰り返し: 不可

この鍵を使用するための認証が不要であることを指定します。このタグは、Tag::USER_SECURE_ID と相互排他的です。

このタグはブール値であり、指定可能な値は true（タグが存在する場合）または false（タグが存在しない場合）です。

Tag::NONCE

バージョン: 1、2、3、4

繰り返し: 不可

AES GCM、CBC、CTR 暗号化 / 復号のノンスまたは初期化ベクトル（IV）を提供するか返します。このタグは、暗号化と復号のオペレーション時に begin に渡されます。鍵が Tag::CALLER_NONCE を持つ場合にのみ、begin に渡されます。渡されなかった場合、適切なノンスまたは IV が Keymaster によってランダムに生成され、begin から返されます。

値は blob で、任意の長さのバイト配列です。許可される長さはモードによって異なります。GCM ノンスの長さは 12 バイトで、CBC と CTR の IV の長さは 16 バイトです。

Tag::ORIGIN

バージョン: 1、2、3、4

繰り返し: 不可

鍵が作成された場所がわかっていれば、それを指定します。このタグは、鍵の生成またはインポート時に指定することはできず、Trustlet によって鍵特性に追加する必要があります。

Keymaster 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 サービスをエミュレートするために使用している場合にのみ存在します。

Tag::ORIGINATION_EXPIRE_DATETIME

バージョン: 1、2、3、4

繰り返し: 不可

目的が署名または暗号化である場合に、鍵が期限切れになる日時を指定します。この日時を過ぎてから、KeyPurpose::SIGN または KeyPurpose::ENCRYPT を持つ鍵を begin に渡して使用しようとすると、ErrorCode::KEY_EXPIRED で失敗します。

値は、1970 年 1 月 1 日からのミリ秒数を表す 64 ビットの整数です。

Tag::OS_PATCHLEVEL

バージョン: 2、3、4

繰り返し: 不可

このタグは Keymaster TA に送信されることはありませんが、TA によってハードウェアで適用する承認リストに追加されます。

タグの値は YYYYMM 形式の整数です。YYYY は最終更新日付の 4 桁の年、MM は最終更新日付の 2 桁の月です。たとえば、Android デバイスで生成されて 2015 年 12 月に最後に更新された鍵の場合、値は 201512 になります。

現在のパッチレベルと異なるパッチレベルを持つ鍵は使用できません。そのような鍵を使用しようとすると、begin、getKeyCharacteristics、または exportKey が ErrorCode::KEY_REQUIRES_UPGRADE を返します。詳細については、バージョン バインディングをご覧ください。

Tag::OS_VERSION

バージョン: 2、3、4

繰り返し: 不可

このタグは Keymaster TA に送信されることはありませんが、TA によってハードウェアで適用する承認リストに追加されます。

タグの値は MMmmss 形式の整数です。MM はメジャー バージョン番号、mm はマイナー バージョン番号、ss はサブマイナー バージョン番号です。たとえば、Android バージョン 4.0.3 で生成された鍵の場合、値は 040003 になります。

Tag::PADDING

バージョン: 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_OAEP と PaddingMode::RSA_PKCS1_1_5_ENCRYPT は RSA 暗号化 / 復号鍵にのみ使用され、RSA PKCS#1v2 OAEP パディングと RSA PKCS#1 v1.5 ランダム化パディングをそれぞれ指定します。PaddingMode::RSA_PSS と PaddingMode::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 鍵でのみ、そして ECB および CBC モードでのみ使用できます。

このタグは繰り返し可能です。パディング モードは、begin の呼び出しで指定する必要があります。指定したモードが鍵に対して承認されていない場合、オペレーションは ErrorCode::INCOMPATIBLE_BLOCK_MODE で失敗します。

Tag::PURPOSE

バージョン: 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;

このタグは繰り返し可能です。オペレーションの目的が 1 つであっても、複数の値を持つ鍵を生成できます。オペレーションを開始するために begin 関数が呼び出されたときに、オペレーションの目的が指定されます。オペレーションに指定された目的が鍵によって承認されていない場合、オペレーションは ErrorCode::INCOMPATIBLE_PURPOSE で失敗します。

Tag::RESET_SINCE_ID_ROTATION

バージョン: 3、4

繰り返し: 不可

デバイスが一意の ID の最後のローテーション以降に出荷時設定にリセットされたかどうかを指定します。キー構成証明に使用されます。

このタグはブール値であり、指定可能な値は true（タグが存在する場合）または false（タグが存在しない場合）です。

Tag::ROLLBACK_RESISTANT

バージョン: 1、2、3、4

繰り返し: 不可

鍵にロールバック耐性があることを示します。つまり、鍵が deleteKey または deleteAllKeys によって削除された場合、完全に削除されて使用不可能になることが保証されます。このタグを持たない鍵は、削除後にバックアップから復元できます。

このタグはブール値であり、指定可能な値は true（タグが存在する場合）または false（タグが存在しない場合）です。

Tag::ROOT_OF_TRUST

バージョン: 1、2、3、4

繰り返し: 不可

ルート オブ トラストを指定します。起動されたオペレーティング システム（存在する場合）を検証するために確認付きブートによって使用されます。このタグは鍵特性で KeyMaster に提供されることも KeyMaster から返されることもありません。

Tag::RSA_PUBLIC_EXPONENT

バージョン: 1、2、3、4

繰り返し: 不可

RSA 鍵ペアの公開指数の値を指定します。このタグは RSA 鍵にのみ適用され、すべての RSA 鍵で必須です。

値は、RSA 公開指数の要件を満たす 64 ビットの符号なし整数です。この値は素数でなければなりません。Trustlet は値 2^16+1 をサポートします。他の妥当な値（特に 3）もサポートできます。指数を指定しなかった場合、または指定した指数がサポートされていない場合、鍵の生成は ErrorCode::INVALID_ARGUMENT で失敗します。

Tag::UNIQUE_ID

バージョン: 3、4

繰り返し: 不可

構成証明で一意の ID を提供するために使用されます。

値は blob で、任意の長さのバイト配列です。

Tag::USAGE_EXPIRE_DATETIME

バージョン: 1、2、3、4

繰り返し: 不可

目的が検証または復号である場合に、鍵が期限切れになる日時を指定します。この日時を過ぎてから、KeyPurpose::VERIFY または KeyPurpose::DECRYPT を持つ鍵を begin に渡して使用しようとすると、ErrorCode::KEY_EXPIRED で失敗します。

値は、1970 年 1 月 1 日からのミリ秒数を表す 64 ビットの整数です。

Tag::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;

Tag::USER_SECURE_ID

バージョン: 1、2、3、4

繰り返し: 可能

特定のセキュアなユーザー認証状態でのみ鍵を使用できることを指定します。このタグは、Tag::NO_AUTH_REQUIRED と相互排他的です。

値は、認証ポリシー状態の値を指定する 64 ビットの整数です。この値は、鍵の使用を承認するために認証トークン内に存在する必要があります（認証トークンは Tag::AUTH_TOKEN で begin に渡されます）。認証トークンを提供しなかった場合、または一致するポリシー状態値を持たない認証トークンを提供した場合、このタグを持つ鍵による begin の呼び出しはすべて失敗します。

このタグは繰り返し可能です。指定された値のいずれかが認証トークン内のポリシー状態値と一致する場合、鍵の使用は承認されます。一致しない場合、オペレーションは ErrorCode::KEY_USER_NOT_AUTHENTICATED で失敗します。

Tag::VENDOR_PATCHLEVEL

バージョン: 4

このタグは、鍵を使用できるベンダー イメージのセキュリティ パッチレベルを指定します。このタグは Keymaster TA に送信されることはありませんが、TA によってハードウェアで適用する承認リストに追加されます。Tag::VENDOR_PATCHLEVEL の値が現在実行中のシステム パッチレベルと異なる鍵を使用しようとすると、begin()、getKeyCharacteristics()、または exportKey() が ErrorCode::KEY_REQUIRES_UPGRADE を返します。詳しくは、upgradeKey() をご覧ください。

タグの値は YYYYMMDD 形式の整数です。YYYY は最終更新日付の 4 桁の年、MM は 2 桁の月、DD は 2 桁の日です。たとえば、Android デバイスで生成された鍵が 2018 年 6 月 5 日に最後に更新された場合、値は 20180605 になります。

IKeymasterDevice HAL は、システム プロパティ ro.vendor.build.security_patch から現在のベンダー パッチレベルを読み取って、HAL が最初に読み込まれる際にセキュア環境に配信する必要があります（メカニズムは実装で定義します）。セキュア環境は、次回の起動後まで別のパッチレベルを受け入れないようにする必要があります。

ハードウェアで適用する必要があります。