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

BCryptCreateMultiHashFn

コールバック

シグネチャ

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

パラメーター

フィールド型説明
hAlgorithmBCRYPT_ALG_HANDLE

BCRYPT_ALG_HANDLE [in, out]

マルチハッシュ配列内のすべてのハッシュ状態に使用されるアルゴリズムハンドルです。このアルゴリズムハンドルは、BCryptOpenAlgorithmProvider 関数に BCYRPT_MULTI_FLAG を渡して開かれている必要があります。あるいは、呼び出し元は疑似ハンドルを使用することもできます。

phHashBCRYPT_HASH_HANDLE*

BCRYPT_HASH_HANDLE* [out]

マルチハッシュ状態を表すハンドルを受け取る BCRYPT_HASH_HANDLE 値へのポインターです。このハンドルは、BCryptProcessMultiOperations などの後続の操作で使用します。このハンドルの使用が終わったら、BCryptDestroyHash 関数に渡して解放してください。

nHashesDWORD

ULONG [in]

配列内の要素数です。この関数が作成するマルチハッシュ状態は、nHashes 個の異なるハッシュ状態に対して並列計算を実行できます。

pbHashObjectBYTE*

PUCHAR [out]

マルチハッシュ状態を受け取るバッファーへのポインターです。

サイズは、BCRYPT_MULTI_OBJECT_LENGTH_STRUCT 構造体の cbPerObject メンバーと cbPerElement メンバーから計算できます。値は次のとおりです: cbPerObject + (number of hash states) * cbPerElement。

pbHashObject が NULL で、cbHashObject の値が 0 (0) の場合、オブジェクト用のバッファーは自動的に割り当てられます。

cbHashObjectDWORD

ULONG [in]

pbHashObject バッファーのサイズです。pbHashObject が NULL の場合は 0 (0) を指定します。

pbSecretBYTE*

PUCHAR [in]

ハッシュまたは MAC に使用するキーを格納したバッファーへのポインターです。cbSecret パラメーターには、このバッファーのサイズを指定します。このキーは、BCryptOpenAlgorithmProvider 関数で BCRYPT_ALG_HANDLE_HMAC フラグを使用して開かれたハッシュアルゴリズムにのみ適用されます。それ以外の場合は、このパラメーターに NULL を設定します。

配列のすべての要素に対して同じキーが使用されます。

cbSecretDWORD

ULONG [in]

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

dwFlagsDWORD

ULONG [in]

関数の動作を変更するフラグです。0 または以下の値を指定できます。マルチハッシュオブジェクトは常に再利用可能であり、常に BCRYPT_HASH_REUSABLE_FLAG が渡された場合と同じように動作します。このフラグは一貫性のためにサポートされています。

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

公式ドキュメント

BCryptCreateMultiHash 関数は、複数のハッシュ演算を並列に計算できるマルチハッシュ状態を作成します。このマルチハッシュ状態は、BCryptProcessMultiOperations 関数で使用されます。マルチハッシュ状態は、BCryptCreateHash で作成されるものと同等のハッシュオブジェクトの配列と考えることができます。

並列計算は、個々の計算のレイテンシーが増加する代わりに、全体のスループットを大幅に向上させることができます。

並列ハッシュ計算は、現時点では SHA-256、SHA-384、SHA-512 に対してのみ実装されています。他のハッシュアルゴリズムも並列計算 API で使用できますが、逐次的なハッシュ演算と同じスループットで動作します。並列計算の恩恵を受けられるハッシュアルゴリズムの範囲は、将来の更新で変更される可能性があります。

戻り値

関数の成功または失敗を示すステータスコードを返します。メソッドが成功した場合は STATUS_SUCCESS を返します。その他の NTSTATUS 値については、「NTSTATUS Values」を参照してください。

解説(Remarks)

内部的には、並列ハッシュ計算は単一命令複数データ (SIMD) 命令を使用して行われ、ハッシュアルゴリズムと利用可能な CPU の機能に応じて、最大 8 個の計算が同時に並列処理されます。パフォーマンスを最大化するために、並列処理できる計算を少なくとも 8 個指定することをお勧めします。

長さが不揃いな計算の場合、並列に指定する計算の数を増やすことで、実装が CPU レジスタ全体にわたって計算をより適切にスケジュールできるようになります。これによりスループットの向上が期待できます。最適なスループットを得るには、呼び出し元が 8 個から 100 個の計算を指定することをお勧めします。この範囲で小さい値を選ぶのは、すべてのハッシュ計算の長さが同じ場合だけにしてください。

マルチハッシュは、HMAC-MD2、HMAC-MD4、GMAC ではサポートされていません。

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