Fungsi BCryptOpenAlgorithmProvider (bcrypt.h)

Artikel
02/26/2024

Fungsi BCryptOpenAlgorithmProvider memuat dan menginisialisasi penyedia CNG.

Sintaks

NTSTATUS BCryptOpenAlgorithmProvider(
  [out] BCRYPT_ALG_HANDLE *phAlgorithm,
  [in]  LPCWSTR           pszAlgId,
  [in]  LPCWSTR           pszImplementation,
  [in]  ULONG             dwFlags
);

Parameter

[out] phAlgorithm

Penunjuk ke variabel BCRYPT_ALG_HANDLE yang menerima handel penyedia CNG. Setelah Anda selesai menggunakan handel ini, lepaskan dengan meneruskannya ke fungsi BCryptCloseAlgorithmProvider .

[in] pszAlgId

Penunjuk ke string Unicode yang dihentikan null yang mengidentifikasi algoritma kriptografi yang diminta. Ini bisa menjadi salah satu Pengidentifikasi Algoritma CNG standar atau pengidentifikasi untuk algoritma terdaftar lainnya.

[in] pszImplementation

Penunjuk ke string Unicode yang dihentikan null yang mengidentifikasi penyedia tertentu untuk dimuat. Ini adalah alias terdaftar dari penyedia primitif kriptografi. Parameter ini bersifat opsional dan dapat berupa NULL jika tidak diperlukan. Jika parameter ini NULL, penyedia default untuk algoritma yang ditentukan akan dimuat.

Catatan Jika nilai parameter pszImplementation adalah NULL, CNG mencoba membuka setiap penyedia terdaftar, dalam urutan prioritas, untuk algoritma yang ditentukan oleh parameter pszAlgId dan mengembalikan handel penyedia pertama yang berhasil dibuka. Untuk masa pakai handel, SETIAP API kriptografi BCrypt*** akan menggunakan penyedia yang berhasil dibuka.

Windows Server 2008 dan Windows Vista: CNG mencoba untuk kembali ke penyedia Microsoft CNG.

Berikut ini adalah nama penyedia yang telah ditentukan sebelumnya.

Nilai	Makna
MS_PRIMITIVE_PROVIDER "Penyedia Primitif Microsoft"	Mengidentifikasi penyedia Microsoft CNG dasar.
MS_PLATFORM_CRYPTO_PROVIDER L"Penyedia Kripto Platform Microsoft"	Mengidentifikasi penyedia penyimpanan kunci TPM yang disediakan oleh Microsoft.

[in] dwFlags

Bendera yang mengubah perilaku fungsi. Ini bisa nol atau kombinasi dari satu atau beberapa nilai berikut.

Nilai	Makna
BCRYPT_ALG_HANDLE_HMAC_FLAG	Penyedia akan melakukan algoritma Kode Autentikasi Pesan Berbasis Hash (HMAC) dengan algoritma hash yang ditentukan. Bendera ini hanya digunakan oleh penyedia algoritma hash.
BCRYPT_PROV_DISPATCH	Memuat penyedia ke dalam kumpulan memori yang tidak disebarkan. Jika bendera ini tidak ada, penyedia dimuat ke dalam kumpulan memori halaman. Ketika bendera ini ditentukan, handel yang dikembalikan tidak boleh ditutup sebelum semua objek dependen telah dibebaskan. Catatan Bendera ini hanya didukung dalam mode kernel dan memungkinkan operasi berikutnya pada penyedia diproses pada tingkat Pengiriman. Jika penyedia tidak mendukung dipanggil pada tingkat pengiriman, maka penyedia akan mengembalikan kesalahan ketika dibuka menggunakan bendera ini. Windows Server 2008 dan Windows Vista: Bendera ini hanya didukung oleh penyedia algoritma Microsoft dan hanya untuk algoritma hash dan algoritma kriptografi kunci konten.
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.

Nilai kembali

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

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

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Fungsi berhasil.
STATUS_NOT_FOUND	Tidak ada penyedia yang ditemukan untuk ID algoritma yang ditentukan.
STATUS_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.
STATUS_NO_MEMORY	Terjadi kegagalan alokasi memori.

Keterangan

Karena jumlah dan jenis operasi yang diperlukan untuk menemukan, memuat, dan menginisialisasi penyedia algoritma, fungsi BCryptOpenAlgorithmProvider adalah fungsi intensif yang relatif waktu. Karena itu, kami sarankan Anda menyimpan penyedia algoritma apa pun yang akan Anda gunakan lebih dari sekali, daripada membuka dan menutup penyedia algoritma berulang-ulang.

BCryptOpenAlgorithmProvider dapat dipanggil baik dari mode pengguna atau mode kernel. Pemanggil mode kernel harus dijalankan di PASSIVE_LEVELIRQL.

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.

Mulai Windows 10, CNG tidak lagi mengikuti setiap pembaruan untuk konfigurasi kriptografi. Perubahan tertentu, seperti menambahkan penyedia default baru atau mengubah urutan preferensi penyedia algoritma, mungkin memerlukan boot ulang. Karena itu, Anda harus melakukan boot ulang sebelum memanggil BCryptOpenAlgorithmProvider dengan penyedia yang baru dikonfigurasi.

Persyaratan

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

Lihat juga

BCryptCloseAlgorithmProvider

Share via