keymaster2_device構造体リファレンス

データフィールド
keymaster2_device構造体リファレンス

#include < keymaster2.h >

データフィールド

struct hw_device_t一般
空所 *環境
uint32_tフラグ
keymaster_error_t （* configure ）（const struct keymaster2_device * dev、const keymaster_key_param_set_t * params）
keymaster_error_t （* add_rng_entropy ）（const struct keymaster2_device * dev、const uint8_t * data、size_t data_length）
keymaster_error_t （* generate_key ）（const struct keymaster2_device * dev、const keymaster_key_param_set_t * params、 keymaster_key_blob_t * key_blob、 keymaster_key_characteristics_t * characteristics）
keymaster_error_t （* get_key_characteristics ）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key_blob、const keymaster_blob_t * client_id、const keymaster_blob_t * app_data、 keymaster_key_characteristics_t * characteristics）
keymaster_error_t （* import_key ）（const struct keymaster2_device * dev、const keymaster_key_param_set_t * params、 keymaster_key_format_t key_format、const keymaster_blob_t * key_data、 keymaster_key_blob_t * key_blob、 keymaster_key_characteristics_t * characteristics）
keymaster_error_t （* export_key ）（const struct keymaster2_device * dev、 keymaster_key_format_t export_format、const keymaster_key_blob_t * key_to_export、const keymaster_blob_t * client_id、const keymaster_blob_t * app_data、 keymaster_blob_t * export_data）
keymaster_error_t （* attest_key ）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key_to_attest、const keymaster_key_param_set_t * attest_params、 keymaster_cert_chain_t * cert_chain）
keymaster_error_t （* upgrade_key ）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key_to_upgrade、const keymaster_key_param_set_t * upgrade_params、 keymaster_key_blob_t * upgraded_key）
keymaster_error_t （* delete_key ）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key）
keymaster_error_t （* delete_all_keys ）（const struct keymaster2_device * dev）
keymaster_error_t （* begin ）（const struct keymaster2_device * dev、 keymaster_purpose_t Purpose 、const keymaster_key_blob_t * key、 c​​onst keymaster_key_param_set_t * in_params、 keymaster_key_param_set_t * out_params、 keymaster_operation_handle_t * operation_handle）
keymaster_error_t （* update ）（const struct keymaster2_device * dev、 keymaster_operation_handle_t operation_handle、const keymaster_key_param_set_t * in_params、const keymaster_blob_t * input、size_t * input_consumed、 keymaster_key_param_set_t * out_params、 keymaster_blob_t * output）
keymaster_error_t （* finish ）（const struct keymaster2_device * dev、 keymaster_operation_handle_t operation_handle、const keymaster_key_param_set_t * in_params、const keymaster_blob_t * input、const keymaster_blob_t * signature、 keymaster_key_param_set_t * out_params、 keymaster_blob_t * output）
keymaster_error_t （*中止）（const struct keymaster2_device * dev、 keymaster_operation_handle_t operation_handle）

詳細な説明

Keymaster2デバイス定義

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

フィールドドキュメント

keymaster_error_t （* abort）（const struct keymaster2_device * dev、 keymaster_operation_handle_t operation_handle）

begin（）で開始された暗号化操作を中止し、すべての内部リソースを解放して、 operation_handleを無効にします。

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

keymaster_error_t （* add_rng_entropy）（const struct keymaster2_device * dev、const uint8_t * data、size_t data_length）

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

パラメーター
[の]開発者キーマスターデバイスの構造。
[の]データ混合するランダムデータ。
[の] data_length dataの長さ。

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

keymaster_error_t （* attest_key）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key_to_attest、const keymaster_key_param_set_t * attest_params、 keymaster_cert_chain_t * cert_chain）

キーマスターにkey_to_attestが存在することを証明する署名付きX.509証明書チェーンを生成します（TODO（swillden）：証明書の内容をより詳細に説明します）。証明書には、OID 1.3.6.1.4.1.11129.2.1.17の拡張子と、キーの説明を含む<TODO：swillden –ここにリンクを挿入>で定義された値が含まれます。

パラメーター
[の]開発者キーマスターデバイスの構造。
[の] key_to_attestアテステーション証明書が生成されるキーマスターキー。
[の] attest_paramsアテステーションの実行方法を定義するパラメーター。現在、唯一のパラメータはKM_TAG_ALGORITHMであり、KM_ALGORITHM_ECまたはKM_ALGORITHM_RSAのいずれかである必要があります。これにより、プロビジョニングされた証明書キーのどれを使用して証明書に署名するかが選択されます。
[アウト] cert_chain DERでエンコードされたX.509証明書の配列。 1つ目は、 key_to_attestの証明書になります。残りのエントリはルートにチェーンバックします。呼び出し元は所有権を取得し、keymaster_free_cert_chainの割り当てを解除する必要があります。

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

keymaster_error_t （* begin）（const struct keymaster2_device * dev、 keymaster_purpose_t Purpose 、const keymaster_key_blob_t * key、 c​​onst keymaster_key_param_set_t * in_params、 keymaster_key_param_set_t * out_params、 keymaster_operation_handle_t * operation_handle）

指定されたキーを使用して暗号化操作を開始します。すべてが順調である場合、 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を返します）。

パラメーター
[の]開発者キーマスターデバイスの構造。
[の]目的操作の目的は、KM_PURPOSE_ENCRYPT、KM_PURPOSE_DECRYPT、KM_PURPOSE_SIGN、またはKM_PURPOSE_VERIFYのいずれかです。 AEADモードの場合、暗号化と復号化はそれぞれ署名と検証を意味しますが、KM_PURPOSE_ENCRYPTおよびKM_PURPOSE_DECRYPTとして指定する必要があることに注意してください。
[の]鍵操作に使用するキー。 keyにはpurposeと互換性のある目的があり、その使用要件がすべて満たされている必要があります。そうでない場合、 begin（）は適切なエラーコードを返します。
[の] 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行で定義されています。

struct hw_device_t common

キーマスターデバイスの一般的な方法。この構造のユーザーは、hw_device_tがkeymaster_deviceを参照していることがわかっているコンテキストで、 hw_device_tをkeymaster_deviceポインターにキャストするため、これはkeymaster_deviceの最初のメンバーである必要があります。

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

keymaster_error_t （* configure）（const struct keymaster2_device * dev、const keymaster_key_param_set_t * params）

キーマスターを構成します。このメソッドは、デバイスを開いた後、使用する前に1回呼び出す必要があります。これは、KM_TAG_OS_VERSIONおよびKM_TAG_OS_PATCHLEVELをキーマスターに提供するために使用されます。このメソッドが呼び出されるまで、他のすべてのメソッドはKM_ERROR_KEYMASTER_NOT_CONFIGUREDを返します。このメソッドによって提供される値は、ブートごとに1回だけキーマスターによって受け入れられます。後続の呼び出しはKM_ERROR_OKを返しますが、何もしません。

キーマスターの実装がセキュアハードウェアにあり、提供されたOSバージョンとパッチレベルの値がブートローダーによってセキュアハードウェアに提供された値と一致しない場合（またはブートローダーが値を提供しなかった場合）、このメソッドはKM_ERROR_INVALID_ARGUMENTを返します。他のメソッドは引き続きKM_ERROR_KEYMASTER_NOT_CONFIGUREDを返します。

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

void*コンテキスト

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

keymaster_error_t （* delete_all_keys）（const struct keymaster2_device * dev）

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

この関数はオプションであり、実装されていない場合はNULLに設定する必要があります。

パラメーター
[の]開発者キーマスターデバイスの構造。

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

keymaster_error_t （* delete_key）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key）

キーBLOBに関連付けられているキーまたはキーペアを削除します。この関数を呼び出した後、他の操作にキーを使用することはできなくなります。外部の信頼のルートからのキーに適用される場合があります（現在の信頼のルートでは使用できないキー）。

この関数はオプションであり、実装されていない場合はNULLに設定する必要があります。

パラメーター
[の]開発者キーマスターデバイスの構造。
[の]鍵削除するキー。

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

keymaster_error_t （* export_key）（const struct keymaster2_device * dev、 keymaster_key_format_t export_format、const keymaster_key_blob_t * key_to_export、const keymaster_blob_t * client_id、const keymaster_blob_t * app_data、 keymaster_blob_t * export_data）

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

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

パラメーター
[の]開発者キーマスターデバイスの構造。
[の] export_formatキーのエクスポートに使用される形式。
[の] key_to_exportエクスポートするための鍵。
[の]クライアントIDクライアントIDブロブ。キー生成中にKM_TAG_APPLICATION_IDで提供されたブロブと一致する必要があります（存在する場合）。
[の]アプリデータアプリケーションデータblob。キー生成中にKM_TAG_APPLICATION_DATAで提供されたblobと一致する必要があります（存在する場合）。
[アウト]データのエクスポートエクスポートされたキーマテリアル。発信者が所有権を引き継ぎます。

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

keymaster_error_t （* finish）（const struct keymaster2_device * dev、 keymaster_operation_handle_t operation_handle、const keymaster_key_param_set_t * in_params、const keymaster_blob_t * input、const keymaster_blob_t * signature、 keymaster_key_param_set_t * out_params、 keymaster

begin（）で開始された暗号化操作を終了し、 operation_handleを無効にします。

パラメーター
[の]開発者キーマスターデバイスの構造。
[の] operation_handle begin（）によって返される操作ハンドル。このハンドルは無効になります。
[の] in_params操作の追加パラメーター。 AEADモードの場合、これはKM_TAG_ADDITIONAL_DATAを指定するために使用されますが、 update（）に入力データが提供されなかった場合に限ります。
[の]入力begin（）の呼び出しで確立されたパラメーターに従って、処理されるデータ。 finish（）は、提供されたすべてのデータを消費するか、KM_ERROR_INVALID_INPUT_LENGTHを返す必要があります。
[の]サインbegin（）呼び出しで指定された目的がKM_PURPOSE_VERIFYであった場合に検証される署名。
[アウト]出力出力データ（ある場合）。呼び出し元は、割り当てられたバッファーの所有権を引き継ぎます。

終了する操作が署名検証またはAEADモードの復号化であり、検証が失敗した場合、 finish（）はKM_ERROR_VERIFICATION_FAILEDを返します。

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

uint32_tフラグ

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

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

keymaster_error_t （* generate_key）（const struct keymaster2_device * dev、const keymaster_key_param_set_t * params、 keymaster_key_blob_t * key_blob、 keymaster_key_characteristics_t * characteristics）

キーまたはキーペアを生成し、キーBLOBおよび/またはキーの説明を返します。

キー生成パラメーターは、 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_NO_AUTH_REQUIREDが存在しない限り、通常は指定する必要があります。存在しない場合、ユーザーは使用するたびに認証する必要があります。

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
パラメーター
[の]開発者キーマスターデバイスの構造。
[の]パラメータキー生成パラメーターの配列
[アウト] 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行で定義されています。

keymaster_error_t （* get_key_characteristics）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key_blob、const keymaster_blob_t * client_id、const keymaster_blob_t * app_data、 keymaster_key_characteristics_t * characteristics）

指定されたキーの特性を返します。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が返されることはないことに注意してください。

パラメーター
[の]開発者キーマスターデバイスの構造。
[の] key_blobから特性を取得するための鍵。
[の]クライアントIDクライアントIDデータ。関連付けられていない場合はNULL。
[の] app_idアプリデータ。関連付けられていない場合はNULL。
[アウト]特徴主な特徴。 NULLであってはなりません。呼び出し元はコンテンツの所有権を引き継ぎ、 keymaster_free_characteristics（）の割り当てを解除する必要があります。

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

keymaster_error_t （* import_key）（const struct keymaster2_device * dev、const keymaster_key_param_set_t * params、 keymaster_key_format_t key_format、const keymaster_blob_t * key_data、 keymaster_key_blob_t * key_blob、 keymaster_key_characteristics_t *特性）

キーまたはキーペアをインポートし、キーBLOBおよび/またはキーの説明を返します。

ほとんどのキーインポートパラメータは、「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
パラメーター
[の]開発者キーマスターデバイスの構造。
[の]パラメータインポートされたキーを定義するパラメーター。
[の] params_count paramsのエントリ数。
[の] key_format key_dataのキーデータの形式を指定します。
[アウト] key_blob不透明なキーブロブを返すために使用されます。 NULL以外である必要があります。呼び出し元は、含まれているkey_materialの所有権を引き継ぎます。
[アウト]特徴インポートされたキーの特性を返すために使用されます。 NULLの場合があります。その場合、特性は返されません。 NULL以外の場合、呼び出し元はコンテンツの所有権を引き継ぎ、 keymaster_free_characteristics（）の割り当てを解除する必要があります。 KM_TAG_APPLICATION_IDとKM_TAG_APPLICATION_DATAが返されることはないことに注意してください。

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

keymaster_error_t （* update）（const struct keymaster2_device * dev、 keymaster_operation_handle_t operation_handle、const keymaster_key_param_set_t * in_params、const keymaster_blob_t * input、size_t * input_consumed、 keymaster_key_param_set_t * out_params、 keymaster_blob_

begin（）で開始される進行中の暗号化操作にデータを提供し、場合によってはそこから出力を受け取ります。

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

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

パラメーター
[の]開発者キーマスターデバイスの構造。
[の] operation_handle begin（）によって返される操作ハンドル。
[の] in_params操作の追加パラメーター。 AEADモードの場合、これはKM_TAG_ADDITIONAL_DATAを指定するために使用されます。 update（）への複数の呼び出しで追加のデータが提供される場合がありますが、入力データが提供されるまでのみであることに注意してください。
[の]入力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行で定義されています。

keymaster_error_t （* upgrade_key）（const struct keymaster2_device * dev、const keymaster_key_blob_t * key_to_upgrade、const keymaster_key_param_set_t * upgrade_params、 keymaster_key_blob_t * upgraded_key）

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

パラメーター
[の]開発者キーマスターデバイスの構造。
[の] key_to_upgradeアップグレードするキーマスターキー。
[の] upgrade_paramsアップグレードを完了するために必要なパラメーター。特に、KM_TAG_APPLICATION_IDとKM_TAG_APPLICATION_DATAは、キーに対して定義されている場合に必要になります。
[アウト] upgrade_keyアップグレードされたキーブロブ。

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

この構造体のドキュメントは、次のファイルから生成されました。