Fungsi BCryptGenerateKeyPair (bcrypt.h)

Fungsi BCryptGenerateKeyPair membuat pasangan kunci publik/privat kosong. Setelah membuat kunci dengan menggunakan fungsi ini, Anda dapat menggunakan fungsi BCryptSetProperty untuk mengatur propertinya; namun, kunci tidak dapat digunakan sampai fungsi BCryptFinalizeKeyPair dipanggil.

Sintaksis

NTSTATUS BCryptGenerateKeyPair(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [out]     BCRYPT_KEY_HANDLE *phKey,
  [in]      ULONG             dwLength,
  [in]      ULONG             dwFlags
);

Parameter

[in, out] hAlgorithm

Menangani penyedia algoritma yang mendukung penandatanganan, enkripsi asimetris, atau perjanjian kunci. Handel ini harus dibuat dengan menggunakan fungsi BCryptOpenAlgorithmProvider .

[out] phKey

Pointer ke BCRYPT_KEY_HANDLE yang menerima handel kunci. Handel ini digunakan dalam fungsi berikutnya yang memerlukan kunci, seperti BCryptEncrypt. Handel ini harus dirilis ketika tidak lagi diperlukan dengan meneruskannya ke fungsi BCryptDestroyKey.

[in] dwLength

Panjangnya, dalam bit, dari kunci. Penyedia algoritma memiliki batasan ukuran kunci yang berbeda untuk setiap algoritma asimetris standar.

Untuk pengidentifikasi algoritma pasca-kuantum, dwLength harus nol.

Pengidentifikasi algoritma	Arti
BCRYPT_DH_ALGORITHM	Ukuran kunci harus lebih besar dari atau sama dengan 512 bit, kurang dari atau sama dengan 4096 bit, dan harus kelipatan 64.
BCRYPT_DSA_ALGORITHM	Sebelum Windows 8, ukuran kunci harus lebih besar dari atau sama dengan 512 bit, kurang dari atau sama dengan 1024 bit, dan harus kelipatan 64. Dimulai dengan Windows 8, ukuran kunci harus lebih besar dari atau sama dengan 512 bit, kurang dari atau sama dengan 3072 bit, dan harus kelipatan 64. Pemrosesan untuk ukuran kunci kurang dari atau sama dengan 1024 bit mematuhi FIPS 186-2. Pemrosesan untuk ukuran kunci yang lebih besar dari 1024 dan kurang dari atau sama dengan 3072 mematuhi FIPS 186-3.
BCRYPT_ECDH_P256_ALGORITHM	Ukuran kunci harus 256 bit.
BCRYPT_ECDH_P384_ALGORITHM	Ukuran kunci harus 384 bit.
BCRYPT_ECDH_P521_ALGORITHM	Ukuran kunci harus 521 bit.
BCRYPT_ECDSA_P256_ALGORITHM	Ukuran kunci harus 256 bit.
BCRYPT_ECDSA_P384_ALGORITHM	Ukuran kunci harus 384 bit.
BCRYPT_ECDSA_P521_ALGORITHM	Ukuran kunci harus 521 bit.
BCRYPT_RSA_ALGORITHM	Ukuran kunci harus lebih besar dari atau sama dengan 512 bit, kurang dari atau sama dengan 16384 bit, dan harus kelipatan 64.

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini. Tidak ada bendera yang saat ini ditentukan, jadi parameter ini harus nol.

Gunakan BCRYPT_NO_KEY_VALIDATION untuk menolak pengujian mandiri FIPS yang berlaku.

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_INVALID_HANDLE	Handel algoritma dalam parameter hAlgorithm tidak valid.
STATUS_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.
STATUS_NOT_SUPPORTED	Penyedia yang ditentukan tidak mendukung enkripsi kunci asimetris.

Komentar

Bergantung pada mode prosesor apa yang didukung penyedia, BCryptGenerateKeyPair dapat dipanggil baik dari mode pengguna atau mode kernel. Pemanggil mode kernel dapat menjalankan baik di PASSIVE_LEVELIRQL atau IRQL DISPATCH_LEVEL. Jika tingkat IRQL saat ini DISPATCH_LEVEL, handel yang disediakan dalam parameter hAlgorithm harus dibuka dengan menggunakan bendera BCRYPT_PROV_DISPATCH , dan setiap pointer yang diteruskan ke fungsi BCryptGenerateKeyPair harus merujuk ke memori yang tidak disebarkan (atau dikunci).

Pemanggil harus membebaskan phKey dengan BCryptDestroyKey ketika kunci selesai digunakan.

Jika handel algoritma XMS atau LMSS diteruskan, fungsi ini akan mengembalikan STATUS_NOT_SUPPORTED karena pembuatan kunci untuk algoritma tanda tangan berbasis hash stateful tidak diizinkan oleh FIPS.

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
Perpustakaan	Bcrypt.lib
DLL	Bcrypt.dll

Lihat juga

BCryptDestroyKey