keymaster2_device 構造体リファレンス

begin() で開始された暗号オペレーションを中止し、すべての内部リソースを解放して operation_handle を無効にします。

ファイル keymaster2.h の 415 行の定義。

Keymaster が使用する RNG にエントロピーを追加します。この方法で追加されたエントロピーが、使用されるエントロピーの唯一のソースではないことが保証され、混合関数は安全である必要があります。つまり、攻撃者が予測（または制御）できないデータで RNG がシードされた場合、RNG の出力はランダムと区別できない必要があります。したがって、任意のソースからのエントロピーが良好であれば、出力も良好になります。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	data	混ぜ込むランダムなデータ。
[in]	data_length	data の長さ。

ファイル keymaster2.h の 74 行 で定義されています。

keymaster に key_to_attest が存在することを証明する署名付き X.509 証明書チェーンを生成します（TODO(swillden): 証明書の内容を詳しく説明）。証明書には、OID 1.3.6.1.4.1.11129.2.1.17 の拡張と、<TODO:swillden – insert link here> で定義された値が含まれ、鍵の説明が含まれています。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	key_to_attest	構成証明証明書が生成される Keymaster 鍵。
[in]	attest_params	構成証明を行う方法を定義するパラメータ。現時点では、唯一のパラメータは KM_TAG_ALGORITHM です。これは KM_ALGORITHM_EC または KM_ALGORITHM_RSA のいずれかにする必要があります。これにより、証明書の署名に使用するプロビジョニングされた構成証明鍵を選択します。
[公開]	cert_chain	DER でエンコードされた X.509 証明書の配列。最初の証明書は key_to_attest の証明書です。残りのエントリはルートに連結されます。呼び出し元が所有権を取得し、keymaster_free_cert_chain で割り当てを解除する必要があります。

ファイル keymaster2.h の 239 行 の定義。

指定された鍵を使用して暗号オペレーションを開始します。問題がなければ、 begin() は KM_ERROR_OK を返してオペレーション ハンドルを作成します。このハンドルは、 update() 、 finish() 、 abort() の呼び出しに渡す必要があります。

キーマスターの実装で内部オペレーションの状態をクリーンアップできるように、 begin() の呼び出しごとに、 finish() または abort() の呼び出しをペアで行うことが重要です。これを行わないと、内部状態空間やその他の内部リソースがリークし、最終的にオペレーション用のスペースが不足すると、 begin() が KM_ERROR_TOO_MANY_OPERATIONS を返す可能性があります。 begin() 、 update() 、または finish() からの KM_ERROR_OK 以外の結果は、オペレーションを暗黙的に中止します。この場合、 abort() を呼び出す必要はありません（呼び出すと KM_ERROR_INVALID_OPERATION_HANDLE が返されます）。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	目的	オペレーションの目的。KM_PURPOSE_ENCRYPT、KM_PURPOSE_DECRYPT、KM_PURPOSE_SIGN、KM_PURPOSE_VERIFY のいずれかです。AEAD モードの場合、暗号化と復号はそれぞれ署名と検証を意味しますが、KM_PURPOSE_ENCRYPT と KM_PURPOSE_DECRYPT として指定する必要があります。
[in]	キー	オペレーションに使用する鍵。 key は purpose と互換性のある目的を持ち、その使用要件をすべて満たしている必要があります。そうしないと、 begin() は適切なエラーコードを返します。
[in]	in_params	オペレーションの追加パラメータ。これは通常、KM_TAG_AUTH_TOKEN を使用して認証データを提供するために使用されます。生成時に KM_TAG_APPLICATION_ID または KM_TAG_APPLICATION_DATA が指定されている場合は、ここで指定する必要があります。指定しない場合、オペレーションは失敗し、KM_ERROR_INVALID_KEY_BLOB が返されます。ノンスまたは IV を必要とするオペレーションの場合、KM_TAG_CALLER_NONCE で生成された鍵では、in_params にタグ KM_TAG_NONCE が含まれている場合があります。
[公開]	out_params	出力パラメータ。オペレーションの初期化から追加のデータを返すために使用されます。特に、IV またはノンスを生成するオペレーションから IV またはノンスを返すために使用されます。呼び出し元は出力パラメータ配列の所有権を取得し、 keymaster_free_param_set() で解放する必要があります。出力パラメータが想定されない場合は、out_params を NULL に設定できます。out_params が NULL で、出力パラメータが生成された場合、 begin() は KM_ERROR_OUTPUT_PARAMETER_NULL を返します。
[公開]	operation_handle	新しく作成されたオペレーション ハンドル。 update() 、 finish() 、または abort() に渡す必要があります。operation_handle が NULL の場合、 begin() は KM_ERROR_OUTPUT_PARAMETER_NULL を返します。

ファイル keymaster2.h の 332 行目 に定義されています。

Keymaster デバイスの一般的なメソッド。この構造体のユーザーは、 hw_device_t が keymaster_device を参照していることが判明しているコンテキストで、 hw_device_t を keymaster_device ポインタにキャストするため、このメンバーは keymaster_device の最初のメンバーである必要があります。

ファイル keymaster2.h の 35 行目で定義されています。

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 を返します。

ファイル keymaster2.h の 58 行 の定義。

ファイル keymaster2.h の 37 行目 の定義。

ハードウェア キーストア内のすべての鍵を削除します。キーストアが完全にリセットされた場合に使用されます。この関数を呼び出した後、以前に生成またはインポートされた鍵の blob をオペレーションに使用することはできなくなります。

この関数は省略可能で、実装されていない場合は NULL に設定する必要があります。

パラメータ

[in]

dev

Keymaster デバイス構造。

ファイル keymaster2.h の 288 行目の定義。

鍵 BLOB に関連付けられている鍵または鍵ペアを削除します。この関数を呼び出した後、他のオペレーションで鍵を使用することはできません。外部ルート オブ トラスト（現在のルート オブ トラストで使用できない鍵）の鍵に適用できます。

この関数は省略可能で、実装されていない場合は NULL に設定する必要があります。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	キー	削除するキー。

ファイル keymaster2.h の 276 行 で定義されています。

公開鍵または対称鍵をエクスポートし、指定された形式のバイト配列を返します。

対称鍵のエクスポートは、鍵が KM_TAG_EXPORTABLE で作成され、鍵の使用に関するすべての要件（認証など）が満たされている場合にのみ許可されます。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	export_format	鍵のエクスポートに使用する形式。
[in]	key_to_export	エクスポートする鍵。
[in]	client_id	クライアント ID blob。鍵の生成時に KM_TAG_APPLICATION_ID で指定された blob（存在する場合）と一致している必要があります。
[in]	app_data	アプリケーション データ blob。鍵の生成時に KM_TAG_APPLICATION_DATA で指定された blob（存在する場合）と一致する必要があります。
[公開]	export_data	エクスポートされた鍵マテリアル。呼び出し元が所有権を取得します。

ファイル keymaster2.h の 213 行目の定義。

begin() で開始された暗号オペレーションを終了し、 operation_handle を無効にします。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	operation_handle	begin() によって返されるオペレーション ハンドル。このハンドルは無効になります。
[in]	in_params	オペレーションの追加パラメータ。AEAD モードでは、 update() に入力データが提供されていない場合にのみ、KM_TAG_ADDITIONAL_DATA を指定するために使用されます。
[in]	入力	begin() の呼び出しで設定されたパラメータに従って処理されるデータ。 finish() は、指定されたデータをすべて使用するか、KM_ERROR_INVALID_INPUT_LENGTH を返す必要があります。
[in]	signature	begin() 呼び出しで指定された目的が KM_PURPOSE_VERIFY の場合に検証される署名。
[公開]	出力	出力データ（ある場合）。呼び出し元は、割り振られたバッファの所有権を取得します。

終了するオペレーションが署名検証または AEAD モードの復号で、検証が失敗した場合、 finish() は KM_ERROR_VERIFICATION_FAILED を返します。

ファイル keymaster2.h の 405 行目の定義。

keymaster_common.h で keymaster0_devices::flags に定義されているフラグをご覧ください。下位互換性のためにのみ使用されます。keymaster2 ハードウェア デバイスでは、この値をゼロに設定する必要があります。

ファイル keymaster2.h の 43 行 の定義。

鍵または鍵ペアを生成し、鍵 blob や鍵の説明を返します。

鍵生成パラメータは、 params で指定される Keymaster のタグと値のペアとして定義されます。完全なリストについては、keymaster_tag_t をご覧ください。有用な鍵の生成に常に必要な値は次のとおりです。

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE。
• （KM_TAG_USER_SECURE_ID と KM_TAG_USER_AUTH_TYPE）または KM_TAG_NO_AUTH_REQUIRED です。

通常、KM_TAG_NO_AUTH_REQUIRED が存在する場合を除き、KM_TAG_AUTH_TIMEOUT を指定する必要があります。指定しない場合、ユーザーは使用のたびに認証する必要があります。

必要なアルゴリズムには、KM_TAG_BLOCK_MODE、KM_TAG_PADDING、KM_TAG_MAC_LENGTH、KM_TAG_DIGEST を指定する必要があります。

次のタグは指定できません。値は実装によって提供されます。

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT
• KM_TAG_CREATION_DATETIME

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	params	鍵生成パラメータの配列
[公開]	key_blob	生成された鍵を返します。 key_blob は NULL にできません。呼び出し元は key_blob->key_material の所有権を取得し、free() する必要があります。
[公開]	特性	生成された鍵の特性（NULL 以外の場合）を返します。NULL でない場合、呼び出し元が所有権を取得し、 keymaster_free_characteristics() で割り当てを解除する必要があります。KM_TAG_ROOT_OF_TRUST、KM_TAG_APPLICATION_ID、KM_TAG_APPLICATION_DATA は返されません。

ファイル keymaster2.h の 112 行 の定義。

指定された鍵の特性、または key_blob が無効な場合は KM_ERROR_INVALID_KEY_BLOB を返します（実装では鍵の完全性を完全に検証する必要があります）。client_id と app_data は、鍵の生成またはインポート時に指定された ID とデータである必要があります。生成時に KM_TAG_APPLICATION_ID または KM_TAG_APPLICATION_DATA が指定されていない場合は空にする必要があります。これらの値は、返される特性には含まれません。呼び出し元は、割り振られた特性オブジェクトの所有権を取得します。このオブジェクトは、 keymaster_free_characteristics() で割り当て解除する必要があります。

KM_TAG_APPLICATION_ID と KM_TAG_APPLICATION_DATA は返されません。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	key_blob	特性を取得するキー。
[in]	client_id	クライアント ID データ。関連付けられていない場合は NULL。
[in]	app_id	アプリデータ。関連付けられていない場合は NULL。
[公開]	特性	主な特徴。NULL にすることはできません。呼び出し元はコンテンツの所有権を取得し、 keymaster_free_characteristics() で割り当てを解除する必要があります。

ファイル keymaster2.h の 139 行 の定義。

鍵または鍵ペアをインポートし、鍵 blob や鍵の説明を返します。

ほとんどの鍵インポート パラメータは、Keymaster のタグと値のペアとして定義され、「params」で指定されます。完全なリストについては、keymaster_tag_t をご覧ください。有用なキーのインポートに常に必要な値は次のとおりです。

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE。
• （KM_TAG_USER_SECURE_ID と KM_TAG_USER_AUTH_TYPE）または KM_TAG_NO_AUTH_REQUIRED です。

通常は KM_TAG_AUTH_TIMEOUT を指定する必要があります。指定しない場合、ユーザーは使用のたびに認証する必要があります。

次のタグは、指定しない場合、デフォルト値が使用されます。

• KM_TAG_KEY_SIZE は、デフォルトで指定された鍵のサイズになります。
• KM_TAG_RSA_PUBLIC_EXPONENT は、デフォルトで指定された鍵の値になります（RSA 鍵の場合）。

次のタグは指定できません。値は実装によって提供されます。

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT
• KM_TAG_CREATION_DATETIME

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	params	インポートされた鍵を定義するパラメータ。
[in]	params_count	params 内のエントリの数。
[in]	key_format	key_data 内の鍵データの形式を指定します。
[公開]	key_blob	不透明な鍵 blob を返すために使用されます。null 以外にする必要があります。呼び出し元は、含まれる key_material の所有権を取得します。
[公開]	特性	インポートされた鍵の特性を返すために使用されます。NULL にすることもできます。この場合、特徴は返されません。NULL でない場合、呼び出し元はコンテンツの所有権を取得し、 keymaster_free_characteristics() で割り当てを解除する必要があります。KM_TAG_APPLICATION_ID と KM_TAG_APPLICATION_DATA は返されません。

ファイル keymaster2.h の 186 行目 の定義。

begin() で開始された進行中の暗号オペレーションにデータを提供します。また、出力を受け取ることもあります。

operation_handle が無効な場合、 update() は KM_ERROR_INVALID_OPERATION_HANDLE を返します。

update() は、データバッファで提供されたすべてのデータを消費しない場合があります。 update() は、*data_consumed で消費された量を返します。呼び出し元は、未使用のデータを後続の呼び出しで提供する必要があります。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	operation_handle	begin() によって返されるオペレーション ハンドル。
[in]	in_params	オペレーションの追加パラメータ。AEAD モードでは、KM_TAG_ADDITIONAL_DATA を指定するために使用されます。追加データを複数回 update() に指定できますが、入力データが指定されるまでです。
[in]	入力	begin() の呼び出しで設定されたパラメータに従って処理されるデータ。 update() は、指定されたデータをすべて消費する場合と消費しない場合がある点に注意してください。 input_consumed をご覧ください。
[公開]	input_consumed	update() によって消費されたデータの量。これが指定された金額より少ない場合、呼び出し元は、 update() の呼び出しで残りの金額を指定する必要があります。
[公開]	out_params	出力パラメータ。オペレーションから追加データを返すために使用されます。呼び出し元は出力パラメータ配列の所有権を取得し、 keymaster_free_param_set() で解放する必要があります。出力パラメータが想定されない場合は、out_params を NULL に設定できます。out_params が NULL で、出力パラメータが生成された場合、 begin() は KM_ERROR_OUTPUT_PARAMETER_NULL を返します。
[公開]	出力	出力データ（ある場合）。呼び出し元は、割り振られたバッファの所有権を取得します。出力は NULL にできません。

update() が出力を返さない場合があります。その場合、output->data_length はゼロになり、output->data は NULL または長さがゼロになります（そのため、呼び出し元は常に free() する必要があります）。

ファイル keymaster2.h の 376 行の定義。

古い鍵をアップグレードします。鍵が「古い」状態になるには、2 つの方法があります。Keymaster を新しいバージョンにアップグレードするか、システムを更新して OS バージョンやパッチレベルを無効にします。どちらの場合も、古いキーを使用しようとすると、Keymaster から KM_ERROR_KEY_REQUIRES_UPGRADE が返されます。このメソッドを呼び出して鍵をアップグレードする必要があります。

パラメータ

[in]	dev	Keymaster デバイス構造。
[in]	key_to_upgrade	アップグレードする Keymaster キー。
[in]	upgrade_params	アップグレードを完了するために必要なパラメータ。特に、KM_TAG_APPLICATION_ID と KM_TAG_APPLICATION_DATA は、鍵に定義されている場合に必要になります。
[公開]	upgraded_key	アップグレードされた鍵 blob。

ファイル keymaster2.h の 260 行目の定義。