keymaster2_device 構造体のリファレンス
#include < keymaster2.h >
詳細な説明
Keymaster2 デバイス定義
ファイルkeymaster2.hの28行目の定義。
フィールドドキュメント
| keymaster_error_t (* 中止)(const struct keymaster2_device *dev, keymaster_operation_handle_t操作ハンドル) |
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の長さ。
ファイル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) |
keymaster にkey_to_attestが存在することを証明する署名付き X.509 証明書チェーンを生成します (TODO(swillden): 証明書の内容を詳しく説明します)。証明書には、OID 1.3.6.1.4.1.11129.2.1.17 の拡張子と、キーの説明を含む <TODO:swillden – insert link here> で定義された値が含まれます。
- パラメーター
[で] 開発者 キーマスターデバイスの構造。 [で] 証明する鍵 構成証明証明書が生成されるキーマスター キー。 [で] attest_params 構成証明の実行方法を定義するパラメータ。現時点では、パラメータは KM_TAG_ALGORITHM のみであり、これは KM_ALGORITHM_EC または KM_ALGORITHM_RSA のいずれかである必要があります。これにより、プロビジョニングされた認証キーのどれを使用して証明書に署名するかを選択します。 [外] 証明書チェーン 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 purposes, const keymaster_key_blob_t *key, const 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 で失敗します。 nonce または IV を必要とする操作の場合、KM_TAG_CALLER_NONCE で生成されたキーの in_params にタグ KM_TAG_NONCE が含まれる場合があります。 [外] out_params 出力パラメータ。オペレーションの初期化から追加データを返すために使用されます。特に、IV または nonce を生成するオペレーションから IV または nonce を返すために使用されます。呼び出し元は出力パラメーター配列の所有権を取得し、 keymaster_free_param_set()を使用して解放する必要があります。出力パラメータが予期されない場合は、out_params を NULL に設定できます。 out_params が NULL で、出力パラメーターが生成された場合、 begin()は KM_ERROR_OUTPUT_PARAMETER_NULL を返します。 [外] 操作ハンドル 新しく作成された操作ハンドル。 update() 、 finish()またはabort()に渡す必要があります。 Operation_handle が NULL の場合、 begin() はKM_ERROR_OUTPUT_PARAMETER_NULL を返します。
ファイルkeymaster2.hの332行目の定義。
| 構造体 hw_device_t共通 |
キーマスターデバイスの一般的なメソッド。この構造体のユーザーは、 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 回だけ keymaster によって受け入れられます。後続の呼び出しでは 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) |
ハードウェア キーストア内のすべてのキーを削除します。キーストアが完全にリセットされる場合に使用されます。この関数を呼び出した後は、以前に生成またはインポートされたキー BLOB をどの操作にも使用できなくなります。
この関数はオプションであり、実装されていない場合は 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 を使用して作成された場合、およびキーの使用に関する要件 (認証など) がすべて満たされている場合にのみ許可されることに注意してください。
- パラメーター
[で] 開発者 キーマスターデバイスの構造。 [で] エクスポート形式 キーのエクスポートに使用される形式。 [で] エクスポートするキー エクスポートするキー。 [で] クライアントID クライアント ID BLOB。キーの生成中に KM_TAG_APPLICATION_ID で指定された BLOB (存在する場合) と一致する必要があります。 [で] アプリデータ アプリケーション データ BLOB。キーの生成中に KM_TAG_APPLICATION_DATA で指定された BLOB (存在する場合) と一致する必要があります。 [外] データのエクスポート エクスポートされたキーマテリアル。呼び出し元が所有権を引き継ぎます。
ファイルkeymaster2.hの213行目の定義。
| keymaster_error_t (* 終了)(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) |
begin()で開始された暗号化操作を終了し、 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 *特性) |
キーまたはキー ペアを生成し、キー 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
- パラメーター
[で] 開発者 キーマスターデバイスの構造。 [で] パラメータ 鍵生成パラメータの配列 [外] キーブロブ 生成されたキーを返します。 key_blobNULL であってはなりません。呼び出し元は所有権 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 は決して返されないことに注意してください。
- パラメーター
[で] 開発者 キーマスターデバイスの構造。 [で] キーブロブ 特性を取得するためのキー。 [で] クライアントID クライアント ID データ、または関連付けられていない場合は NULL。 [で] アプリ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 *characteristics) |
キーまたはキー ペアをインポートし、キー 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_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_data でキーデータの形式を指定します。 [外] キーブロブ 不透明なキー 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_t *output) |
begin()で始まる進行中の暗号化操作にデータを提供し、場合によってはそこから出力を受け取ります。
Operation_handle が無効な場合、 update() はKM_ERROR_INVALID_OPERATION_HANDLE を返します。
update() は、データ バッファーに提供されたすべてのデータを消費しない場合があります。 update() は*data_consumed で消費された量を返します。呼び出し元は、後続の呼び出しで未消費のデータを提供する必要があります。
- パラメーター
[で] 開発者 キーマスターデバイスの構造。 [で] 操作ハンドル begin()によって返される操作ハンドル。 [で] in_params 操作の追加パラメータ。 AEAD モードの場合、これは KM_TAG_ADDITIONAL_DATA を指定するために使用されます。追加データはupdate()への複数回の呼び出しで提供される可能性がありますが、それは入力データが提供されるまでであることに注意してください。 [で] 入力 begin()の呼び出しで確立されたパラメータごとに処理されるデータ。 update() は、提供されたデータをすべて消費する場合と消費しない場合があることに注意してください。 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 は 0 になり、output->data は NULL または長さ 0 のいずれかになります (したがって、呼び出し元は常に 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 つの方法で「古く」なる可能性があります。Keymaster が新しいバージョンにアップグレードされるか、システムが更新されて OS バージョンやパッチ レベルが無効になる可能性があります。どちらの場合も、古いキーを使用しようとすると、キーマスターは KM_ERROR_KEY_REQUIRES_UPGRADE を返します。次に、このメソッドを呼び出してキーをアップグレードする必要があります。
- パラメーター
[で] 開発者 キーマスターデバイスの構造。 [で] アップグレードの鍵 アップグレードするキーマスター キー。 [で] アップグレードパラメータ アップグレードを完了するために必要なパラメータ。特に、KM_TAG_APPLICATION_ID と KM_TAG_APPLICATION_DATA がキーに定義されている場合はそれらが必要になります。 [外] アップグレードされたキー アップグレードされたキー BLOB。
ファイルkeymaster2.hの260行目の定義。
この構造体のドキュメントは次のファイルから生成されました。