Fungsi BCryptCreateMultiHash (bcrypt.h)

Artikel
03/23/2023

Fungsi BCryptCreateMultiHash membuat status multi-hash yang memungkinkan komputasi paralel dari beberapa operasi hash. Status multi-hash ini digunakan oleh fungsi BCryptProcessMultiOperations . Status multi-hash dapat dianggap sebagai array objek hash, yang masing-masing setara dengan yang dibuat oleh BCryptCreateHash.

Komputasi paralel dapat sangat meningkatkan throughput keseluruhan, dengan mengorbankan peningkatan latensi untuk komputasi individu.

Komputasi hash paralel saat ini hanya diimplementasikan untuk SHA-256, SHA-384, dan SHA-512. Algoritma hash lainnya dapat digunakan dengan API komputasi paralel tetapi berjalan pada throughput operasi hash berurutan. Kumpulan algoritma hash yang dapat memperoleh manfaat dari komputasi paralel mungkin berubah dalam pembaruan di masa mendatang.

Sintaks

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

Parameter

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

Handel algoritma yang digunakan untuk semua status hash dalam array multi-hash. Handel algoritma harus telah dibuka dengan BCYRPT_MULTI_FLAG diteruskan ke fungsi BCryptOpenAlgorithmProvider . Atau, pemanggil dapat menggunakan handel pseudo.

phHash

BCRYPT_HASH_HANDLE* [out]

Penunjuk ke nilai BCRYPT_HASH_HANDLE yang menerima handel yang mewakili status multi-hash. Handel ini digunakan dalam operasi berikutnya seperti BCryptProcessMultiOperations. Setelah Anda selesai menggunakan handel ini, lepaskan dengan meneruskannya ke fungsi BCryptDestroyHash .

nHashes

ULONG[in]

Jumlah elemen dalam array. Status multi-hash yang dibuat fungsi ini mampu melakukan komputasi paralel pada nHashes status hash yang berbeda.

pbHashObject

PUCHAR[out]

Penunjuk ke buffer yang menerima status multi-hash.

Ukuran dapat dihitung dari anggota cbPerObject dan cbPerElement dari struktur BCRYPT_MULTI_OBJECT_LENGTH_STRUCT . Nilainya adalah sebagai berikut: cbPerObject + (number of hash states) * cbPerElement.

Jika pbHashObject adalah NULL dan cbHashObject memiliki nilai nol (0), buffer objek dialokasikan secara otomatis.

cbHashObject

ULONG[in]

Ukuran buffer pbHashObject , atau nol (0) jika pbHashObject adalah NULL.

pbSecret

PUCHAR[in]

Penunjuk ke buffer yang berisi kunci yang akan digunakan untuk hash atau MAC. Parameter cbSecret berisi ukuran buffer ini. Kunci ini hanya berlaku untuk algoritma hash yang dibuka oleh fungsi BCryptOpenAlgorithmProvider dengan menggunakan bendera BCRYPT_ALG_HANDLE_HMAC . Jika tidak, atur parameter ini ke NULL.

Kunci yang sama digunakan untuk semua elemen array.

cbSecret

ULONG[in]

Ukuran, dalam byte, dari penyangga pbSecret . Jika tidak ada kunci yang digunakan, atur parameter ini ke nol (0).

dwFlags

ULONG[in]

Bendera yang mengubah perilaku fungsi. Ini bisa nol atau nilai di bawah ini. Objek multi-hash selalu dapat digunakan kembali dan selalu berperilaku seolah-olah BCRYPT_HASH_REUSABLE_FLAG diteruskan. Bendera ini didukung di sini untuk konsistensi.

Nilai	Makna
BCRYPT_HASH_REUSABLE_FLAG	Membuat objek hashing yang dapat digunakan kembali. Objek dapat digunakan untuk operasi hashing baru segera setelah memanggil BCryptFinishHash. Untuk informasi selengkapnya, lihat Membuat Hash dengan CNG.

Nilai kembali

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi. Jika metode berhasil, metode akan mengembalikan STATUS_SUCCESS. Untuk nilai NTSTATUS lainnya, lihat Nilai NTSTATUS.

Keterangan

Secara internal, komputasi hash paralel dilakukan menggunakan instruksi single-instruction multiple-data (SIMD) dengan hingga 8 komputasi paralel sekaligus, tergantung pada algoritma hash dan fitur CPU yang tersedia. Untuk memaksimalkan performa, sebaiknya penelepon menyediakan setidaknya delapan komputasi yang dapat diproses secara paralel.

Untuk komputasi panjang yang tidak sama, menyediakan lebih banyak komputasi secara paralel memungkinkan implementasi untuk menjadwalkan komputasi dengan lebih baik di seluruh register CPU. Ini dapat memberikan manfaat throughput. Untuk throughput optimal, sebaiknya pemanggil menyediakan antara delapan dan 100 komputasi. Pilih nilai yang lebih rendah dalam rentang tersebut hanya jika semua komputasi hash memiliki panjang yang sama.

Multi-hashing tidak didukung untuk HMAC-MD2, HMAC-MD4, dan GMAC.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8.1 Update [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Pembaruan Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	bcrypt.h
Pustaka	Bcrypt.lib
DLL	Bcrypt.dll