BCryptSignHashFn
コールバックシグネチャ
NTSTATUS BCryptSignHashFn(
BCRYPT_KEY_HANDLE hKey,
void* pPaddingInfo,
BYTE* pbInput,
DWORD cbInput,
BYTE* pbOutput,
DWORD cbOutput,
DWORD* pcbResult,
DWORD dwFlags
);パラメーター
| フィールド | 型 | 説明 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| hKey | BCRYPT_KEY_HANDLE | 署名の生成に使用する秘密キーのハンドルです。 | ||||||||
| pPaddingInfo | void* | パディング情報を格納した構造体へのポインターです。このパラメーターが指す構造体の実際の型は、dwFlags パラメーターの値によって異なります。dwFlags が 0 の場合、このパラメーターは NULL でなければなりません。 | ||||||||
| pbInput | BYTE* | 署名対象の入力を格納したバッファーへのポインターです。cbInput パラメーターには、このバッファーのサイズが格納されます。 多くの署名アルゴリズム (DSA、RSA、ECDSA、HashML-DSA など) では、署名ルーチンはハッシュ関数の結果を入力として受け取るように定義されています。これらのアルゴリズムでは、署名対象の元のメッセージを最初にハッシュする必要があり、その結果得られたハッシュ値 (事前ハッシュ) を pbInput バッファーで渡します。 ただし、一部の署名アルゴリズム (pure ML-DSA、pure SLH-DSA など) では、任意のサイズのデータを直接署名できます。これらのアルゴリズムでは、pbInput バッファーに署名対象の入力を格納します。この入力をどのように構成するかは署名者と検証者の間で合意する必要がありますが、事前ハッシュを伴う必要はありません。非常に大きなバッファーを直接署名すると、相互運用性を損なうおそれがあります。 いずれの場合も、pbInput バッファーは署名対象の入力を表します。 | ||||||||
| cbInput | DWORD | pbInput バッファーのサイズ (バイト単位) です。 | ||||||||
| pbOutput | BYTE* | この関数が生成した署名を受け取るバッファーのアドレスです。cbOutput パラメーターには、このバッファーのサイズが格納されます。 このパラメーターが | ||||||||
| cbOutput | DWORD | pbOutput バッファーのサイズ (バイト単位) です。pbOutput パラメーターが NULL の場合、このパラメーターは無視されます。 | ||||||||
| pcbResult | DWORD* | pbOutput バッファーにコピーされたバイト数を受け取る ULONG 変数へのポインターです。 pbOutput が | ||||||||
| dwFlags | DWORD | この関数の動作を変更するフラグのセットです。指定できるフラグのセットは、hKey パラメーターで指定されたキーの種類によって異なります。 ゼロ、または次のいずれかの値を指定できます。
|
公式ドキュメント
BCryptSignHash 関数は、署名対象のデータに対する署名を作成します。
戻り値
関数の成功または失敗を示すステータスコードを返します。
返される可能性のあるコードには、次のものが含まれます (これらに限定されません)。
| 戻り値 | 説明 |
|---|---|
| STATUS_SUCCESS | 関数は成功しました。 |
| STATUS_INVALID_PARAMETER | 指定されたパラメーターのいずれかが無効です。 |
| STATUS_INVALID_HANDLE | hKey パラメーターで指定されたキーのハンドルが無効です。 |
| STATUS_NO_MEMORY | メモリの割り当てに失敗しました。 |
| STATUS_NOT_SUPPORTED | hKey パラメーターで指定されたキーのハンドルの作成に使用されたアルゴリズムプロバイダーが、署名アルゴリズムではありません。 |
| STATUS_BUFFER_TOO_SMALL | cbOutput パラメーターで指定されたメモリサイズが、署名を格納するのに十分ではありません。 |
解説(Remarks)
この関数は、デジタル署名方式の署名操作を実行します。署名対象のデータと秘密キーを受け取り、dwFlags と pPaddingInfo で必要に応じて指定された追加のパラメーターとともに、対応する公開キーで後から検証できる署名を生成します。
署名が有効であることを後から検証するには、指定した秘密キーに対応する公開キーを含むキーと、検証対象の同一データを指定して BCryptVerifySignature 関数を呼び出します。
サポートされているアルゴリズムプロバイダーを使用する場合、BCryptSignHash はユーザーモードとカーネルモードのいずれからでも呼び出せます。カーネルモードの呼び出し元は、PASSIVE_LEVEL IRQL と DISPATCH_LEVEL IRQL のいずれでも実行できます。現在の IRQL レベルが DISPATCH_LEVEL の場合、hKey パラメーターで指定するハンドルは、BCRYPT_PROV_DISPATCH フラグを指定して開かれたプロバイダーが返すアルゴリズムハンドルから派生したものでなければならず、BCryptSignHash 関数に渡すポインターはすべて非ページメモリ (またはロックされたメモリ) を参照していなければなりません。
カーネルモードでこの関数を呼び出すには、ドライバー開発キット (DDK) に含まれる Cng.lib を使用します。Windows Server 2008 および Windows Vista: カーネルモードでこの関数を呼び出すには、Ksecdd.lib を使用します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)