Fungsi BCryptCreateHash (bcrypt.h)

Fungsi BCryptCreateHash dipanggil untuk membuat objek hash atau Kode Autentikasi Pesan (MAC).

Sintaksis

NTSTATUS BCryptCreateHash(
  [in, out]       BCRYPT_ALG_HANDLE  hAlgorithm,
  [out]           BCRYPT_HASH_HANDLE *phHash,
  [out, optional] PUCHAR             pbHashObject,
  [in]            ULONG              cbHashObject,
  [in, optional]  PUCHAR             pbSecret,
  [in]            ULONG              cbSecret,
  [in]            ULONG              dwFlags
);

Parameter

[in, out] hAlgorithm

Handel penyedia algoritma yang mendukung antarmuka hash atau MAC. Handel ini diperoleh dengan memanggil fungsi BCryptOpenAlgorithmProvider , atau mungkin merupakan CNG Algoritma Pseudo-handle.

[out] phHash

Penunjuk ke nilai BCRYPT_HASH_HANDLE yang menerima handel yang mewakili objek hash atau MAC. Handel ini digunakan dalam fungsi hashing atau MAC berikutnya, seperti fungsi BCryptHashData . Setelah Anda selesai menggunakan handel ini, lepaskan dengan meneruskannya ke fungsi BCryptDestroyHash .

[out, optional] pbHashObject

Penunjuk ke buffer yang menerima objek hash atau MAC. Parameter cbHashObject berisi ukuran buffer ini. Ukuran buffer ini yang diperlukan dapat diperoleh dengan memanggil fungsi BCryptGetProperty untuk mendapatkan properti BCRYPT_OBJECT_LENGTH dari handel algoritma. Ini akan memberikan ukuran objek hash atau MAC untuk algoritma yang ditentukan.

Memori ini hanya dapat dibebaskan setelah handel yang diacu oleh parameter phHash dihancurkan.

Jika nilai parameter ini adalah NULL dan nilai parameter cbHashObject adalah nol, memori untuk objek hash dialokasikan oleh fungsi ini, dan dibebaskan oleh BCryptDestroyHash. Windows 7: Fungsionalitas manajemen memori ini tersedia dimulai dengan Windows 7.

[in] cbHashObject

Ukurannya, dalam byte, dari buffer pbHashObject .

Jika nilai parameter ini nol dan nilai parameter pbHashObject adalah NULL, memori untuk objek kunci dialokasikan oleh fungsi ini, dan dibebaskan oleh BCryptDestroyHash. Windows 7: Fungsionalitas manajemen memori ini tersedia dimulai dengan Windows 7.

[in, optional] pbSecret

Penunjuk ke buffer yang berisi kunci yang akan digunakan untuk MAC. Parameter cbSecret berisi ukuran buffer ini. Jika digunakan dengan algoritma hash, algoritma harus dipromosikan ke HMAC dengan menggunakan bendera BCRYPT_ALG_HANDLE_HMAC di BCryptOpenAlgorithmProvider.

Untuk menghitung hash, atur parameter ini ke NULL.

[in] cbSecret

Ukurannya, dalam byte, dari penyangga pbSecret . Jika tidak ada kunci yang digunakan, atur parameter ini ke nol.

[in] dwFlags

Bendera yang mengubah perilaku fungsi. Ini bisa nol atau nilai berikut:

Nilai	Arti
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. Windows Server 2008 R2, Windows 7, Windows Server 2008 dan Windows Vista: Bendera ini tidak didukung.

Mengembalikan nilai

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

Kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, berikut ini.

Mengembalikan kode	Deskripsi
STATUS_SUCCESS	Fungsi berhasil.
STATUS_BUFFER_TOO_SMALL	Ukuran objek hash yang ditentukan oleh parameter cbHashObject tidak cukup besar untuk menahan objek hash.
STATUS_INVALID_HANDLE	Handel algoritma dalam parameter hAlgorithm tidak valid.
STATUS_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.
STATUS_NOT_SUPPORTED	Penyedia algoritma yang ditentukan oleh parameter hAlgorithm tidak mendukung antarmuka hash atau MAC.

Komentar

Saat menggunakan penyedia algoritma yang didukung, BCryptCreateHash dapat dipanggil baik dari mode pengguna atau mode kernel. Pemanggil mode kernel dapat menjalankan baik di IRQL PASSIVE_LEVEL atau IRQLDISPATCH_LEVEL. Jika tingkat IRQL saat ini DISPATCH_LEVEL, handel yang disediakan dalam parameter hAlgorithm harus dibuka dengan menggunakan bendera BCRYPT_PROV_DISPATCH , dan penunjuk apa pun yang diteruskan ke fungsi BCryptCreateHash harus merujuk ke memori yang tidak dipagasi (atau dikunci).

Pemanggil harus melepaskan phHash dengan BCryptDestroyHash ketika objek tidak lagi digunakan.

Untuk memanggil fungsi ini dalam mode kernel, gunakan Cng.lib, yang merupakan bagian dari Driver Development Kit (DDK). Windows Server 2008 dan Windows Vista: Untuk memanggil fungsi ini dalam mode kernel, gunakan Ksecdd.lib.

Persyaratan

Syarat	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Platform Target	Windows
Header	bcrypt.h
Library	Bcrypt.lib
DLL	Bcrypt.dll

Lihat juga

BCryptDuplicateHash

BCryptHashData

BCryptFinishHash

BCryptDestroyHash