Win32 API 日本語リファレンス
ホーム › Security.Cryptography › BCryptCreateHashFn

BCryptCreateHashFn

コールバック

シグネチャ

NTSTATUS BCryptCreateHashFn(
    BCRYPT_ALG_HANDLE hAlgorithm,
    BCRYPT_HASH_HANDLE* phHash,
    BYTE* pbHashObject,
    DWORD cbHashObject,
    BYTE* pbSecret,
    DWORD cbSecret,
    DWORD dwFlags
);

パラメーター

フィールド型説明
hAlgorithmBCRYPT_ALG_HANDLEハッシュまたは MAC インターフェイスをサポートするアルゴリズムプロバイダーのハンドルです。このハンドルは BCryptOpenAlgorithmProvider 関数を呼び出して取得します。CNG アルゴリズム疑似ハンドル を指定することもできます。
phHashBCRYPT_HASH_HANDLE*ハッシュまたは MAC オブジェクトを表すハンドルを受け取る BCRYPT_HASH_HANDLE 値へのポインターです。このハンドルは、BCryptHashData 関数など、後続のハッシュ処理または MAC 処理の関数で使用します。このハンドルの使用を終えたら、BCryptDestroyHash 関数に渡して解放してください。
pbHashObjectBYTE*

ハッシュまたは MAC オブジェクトを受け取るバッファーへのポインターです。cbHashObject パラメーターには、このバッファーのサイズを指定します。必要なバッファーサイズは、BCryptGetProperty 関数を呼び出してアルゴリズムハンドルから BCRYPT_OBJECT_LENGTH プロパティを取得することで得られます。これにより、指定したアルゴリズムのハッシュまたは MAC オブジェクトのサイズが分かります。

このメモリを解放できるのは、phHash パラメーターが指すハンドルが破棄された後だけです。

このパラメーターの値が NULL で、かつ cbHashObject パラメーターの値が 0 の場合、ハッシュオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyHash によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。

cbHashObjectDWORD

pbHashObject バッファーのサイズ (バイト単位) です。

このパラメーターの値が 0 で、かつ pbHashObject パラメーターの値が NULL の場合、キーオブジェクト用のメモリはこの関数によって割り当てられ、BCryptDestroyHash によって解放されます。Windows 7: このメモリ管理機能は Windows 7 以降で利用できます。

pbSecretBYTE*

MAC に使用するキーを格納したバッファーへのポインターです。cbSecret パラメーターには、このバッファーのサイズを指定します。ハッシュアルゴリズムと共に使用する場合、そのアルゴリズムは BCryptOpenAlgorithmProvider で BCRYPT_ALG_HANDLE_HMAC フラグを使用して HMAC に昇格されている必要があります。

ハッシュを計算する場合は、このパラメーターに NULL を設定します。

cbSecretDWORDpbSecret バッファーのサイズ (バイト単位) です。キーを使用しない場合は、このパラメーターに 0 を設定します。
dwFlagsDWORD

関数の動作を変更するフラグです。0 または次の値を指定できます。

値 意味
BCRYPT_HASH_REUSABLE_FLAG 再利用可能なハッシュオブジェクトを作成します。このオブジェクトは、BCryptFinishHash を呼び出した直後に、新しいハッシュ処理へすぐ使用できます。詳細については、「CNG でのハッシュの作成」を参照してください。

Windows Server 2008 R2、Windows 7、Windows Server 2008、Windows Vista: このフラグはサポートされていません。

公式ドキュメント

BCryptCreateHash 関数は、ハッシュまたは メッセージ認証コード (MAC) オブジェクトを作成するために呼び出されます。

戻り値

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

返される可能性のあるコードには、次のようなものがあります (これらに限定されません)。

戻り値 説明
STATUS_SUCCESS 関数は成功しました。
STATUS_BUFFER_TOO_SMALL cbHashObject パラメーターで指定されたハッシュオブジェクトのサイズが、ハッシュオブジェクトを格納するには小さすぎます。
STATUS_INVALID_HANDLE hAlgorithm パラメーターに指定されたアルゴリズムハンドルが無効です。
STATUS_INVALID_PARAMETER 1 つ以上のパラメーターが無効です。
STATUS_NOT_SUPPORTED hAlgorithm パラメーターで指定されたアルゴリズムプロバイダーが、ハッシュまたは MAC インターフェイスをサポートしていません。

解説(Remarks)

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

呼び出し元は、オブジェクトが不要になった時点で BCryptDestroyHash によって phHash を解放してください。

この関数をカーネルモードで呼び出すには、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)