BCryptCreateMultiHash 関数 (bcrypt.h)

[アーティクル]
03/23/2023

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

並列計算では、個々の計算の待機時間が長くなるのを犠牲にして、全体的なスループットを大幅に向上させることができます。

現在、並列ハッシュ計算は SHA-256、SHA-384、SHA-512 にのみ実装されています。他のハッシュアルゴリズムは並列計算 API で使用できますが、シーケンシャルハッシュ操作のスループットで実行されます。並列計算の恩恵を受けることができるハッシュアルゴリズムのセットは、今後の更新で変更される可能性があります。

構文

NTSTATUS BCryptCreateMultiHash(
  BCRYPT_ALG_HANDLE  hAlgorithm,
  BCRYPT_HASH_HANDLE *phHash,
  ULONG              nHashes,
  PUCHAR             pbHashObject,
  ULONG              cbHashObject,
  PUCHAR             pbSecret,
  ULONG              cbSecret,
  ULONG              dwFlags
);

パラメーター

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

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

phHash

BCRYPT_HASH_HANDLE* [out]

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

nHashes

Ulong[in]

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

pbHashObject

PUCHAR[out]

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

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

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

cbHashObject

Ulong[in]

pbHashObject バッファーのサイズ。pbHashObject がの場合は NULL0 (0) です。

pbSecret

PUCHAR[in]

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

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

cbSecret

Ulong[in]

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

dwFlags

Ulong[in]

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

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

戻り値

関数の成功または失敗を示す状態コードを返します。メソッドが成功すると、が返 STATUS_SUCCESSされます。その他の NTSTATUS 値については、「 NTSTATUS 値」を参照してください。

注釈

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

等しくない長さの計算では、より多くの計算を並列で提供することで、実装では CPU レジスタ全体で計算をより適切にスケジュールできます。これにより、スループットの利点が得られます。スループットを最適化するために、呼び出し元は 8 から 100 の計算を提供することをお勧めします。すべてのハッシュ計算の長さが同じ場合にのみ、その範囲内の小さい値を選択します。

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

要件

要件	値
サポートされている最小のクライアント	Windows 8.1 Update [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 Update [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	bcrypt.h
Library	Bcrypt.lib
[DLL]	Bcrypt.dll