ホーム › Security.Cryptography › BCryptDuplicateHashFn

BCryptDuplicateHashFn

コールバック

シグネチャ

NTSTATUS BCryptDuplicateHashFn(
    BCRYPT_HASH_HANDLE hHash,
    BCRYPT_HASH_HANDLE* phNewHash,
    BYTE* pbHashObject,
    DWORD cbHashObject,
    DWORD dwFlags
);

パラメーター

フィールド	型	説明
hHash	BCRYPT_HASH_HANDLE	複製するハッシュまたは MAC オブジェクトのハンドルです。
phNewHash	BCRYPT_HASH_HANDLE*	複製されたハッシュまたは MAC オブジェクトを表すハンドルを受け取る BCRYPT_HASH_HANDLE 値へのポインターです。このハンドルは、BCryptHashData 関数など、後続のハッシュ関数や MAC 関数で使用します。このハンドルの使用を終えたら、BCryptDestroyHash 関数に渡して解放してください。
pbHashObject	BYTE*	複製されたハッシュまたは MAC オブジェクトを受け取るバッファーへのポインターです。cbHashObject パラメーターには、このバッファーのサイズを指定します。必要なバッファーのサイズは、BCryptGetProperty 関数を呼び出して、アルゴリズムハンドルまたはハッシュハンドルから BCRYPT_OBJECT_LENGTH プロパティを取得することで得られます。これにより、指定したアルゴリズムにおけるハッシュオブジェクトまたは MAC オブジェクトのサイズがわかります。このメモリを解放できるのは、phHash パラメーターが指すハンドルが破棄された後だけです。このパラメーターの値が `NULL` で、cbHashObject パラメーターの値が 0 の場合、ハッシュオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyHash によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。
cbHashObject	DWORD	pbHashObject バッファーのサイズ (バイト単位) です。このパラメーターの値が 0 で、pbHashObject パラメーターの値が `NULL` の場合、キーオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyHash によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。
dwFlags	DWORD	この関数の動作を変更するフラグのセットです。現在定義されているフラグはないため、このパラメーターは 0 にする必要があります。

公式ドキュメント

BCryptDuplicateHash 関数は、既存のハッシュまたはメッセージ認証コード (MAC) オブジェクトを複製します。複製されたオブジェクトには、複製した時点で元のオブジェクトが保持していたすべての状態とデータが含まれます。

戻り値

関数の成功または失敗を示すステータスコードを返します。

返される可能性のあるコードには、次のものが含まれます (ただしこれらに限定されません)。

戻り値	説明
STATUS_SUCCESS	関数は成功しました。
STATUS_BUFFER_TOO_SMALL	cbHashObject パラメーターで指定されたハッシュオブジェクトのサイズが、ハッシュオブジェクトを格納するのに十分ではありません。
STATUS_INVALID_HANDLE	hHash パラメーターのハンドルが有効ではありません。
STATUS_INVALID_PARAMETER	1 つ以上のパラメーターが有効ではありません。

解説(Remarks)

この関数は、共通のデータブロックに対してハッシュまたは MAC を計算する場合に役立ちます。共通データを処理した後でハッシュオブジェクトまたは MAC オブジェクトを複製し、それぞれのオブジェクトに固有のデータを追加できます。

サポートされているアルゴリズムプロバイダーを使用する場合、BCryptDuplicateHash はユーザーモードとカーネルモードのどちらからでも呼び出せます。カーネルモードの呼び出し元は、PASSIVE_LEVEL IRQL または DISPATCH_LEVEL IRQL のいずれでも実行できます。現在の IRQL レベルが DISPATCH_LEVEL の場合、hHash パラメーターに渡すハンドルは、BCRYPT_PROV_DISPATCH フラグを使用して開かれたプロバイダーが返したアルゴリズムハンドルから派生したものでなければならず、BCryptDuplicateHash 関数に渡すポインターはページング対象外の (またはロックされた) メモリを参照している必要があります。

この関数をカーネルモードで呼び出すには、Driver Development Kit (DDK) に含まれる Cng.lib を使用します。Windows Server 2008 および Windows Vista: この関数をカーネルモードで呼び出すには、Ksecdd.lib を使用します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)