Bagikan melalui

Fungsi NCryptCreatePersistedKey (ncrypt.h)

  • Artikel

Fungsi NCryptCreatePersistedKey membuat kunci baru dan menyimpannya di penyedia penyimpanan kunci yang ditentukan. Setelah Anda membuat kunci dengan menggunakan fungsi ini, Anda dapat menggunakan fungsi NCryptSetProperty untuk mengatur propertinya; namun, kunci tidak dapat digunakan sampai fungsi NCryptFinalizeKey dipanggil.

Sintaks

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

Parameter

[in] hProvider

Handel penyedia penyimpanan kunci untuk membuat kunci. Handel ini diperoleh dengan menggunakan fungsi NCryptOpenStorageProvider .

[out] phKey

Alamat variabel NCRYPT_KEY_HANDLE yang menerima handel kunci. Setelah Anda selesai menggunakan handel ini, lepaskan dengan meneruskannya ke fungsi NCryptFreeObject . Untuk menghapus file kunci pada disk, teruskan handel ke fungsi NCryptDeleteKey . Ini juga akan merilis handel. Jadi aplikasi dapat meneruskan handel ke NCryptFreeObject atau NCryptDeleteKey, tetapi tidak keduanya.

[in] pszAlgId

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

[in, optional] pszKeyName

Penunjuk ke string Unicode yang dihentikan null yang berisi nama kunci. Jika parameter ini NULL, fungsi ini akan membuat kunci ephemeral yang tidak bertahan.

[in] dwLegacyKeySpec

Pengidentifikasi warisan yang menentukan jenis kunci. Ini bisa menjadi salah satu nilai berikut:

Nilai Makna
AT_KEYEXCHANGE Kuncinya adalah kunci pertukaran kunci.
AT_SIGNATURE Kuncinya adalah kunci tanda tangan.
0 Kuncinya bukan jenis di atas.

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini. Ini bisa nol atau kombinasi dari satu atau beberapa nilai berikut:

Nilai Makna
NCRYPT_MACHINE_KEY_FLAG Kunci berlaku untuk komputer lokal. Jika bendera ini tidak ada, kunci berlaku untuk pengguna saat ini.
NCRYPT_OVERWRITE_KEY_FLAG Jika kunci sudah ada dalam kontainer dengan nama yang ditentukan, kunci yang ada akan ditimpa. Jika bendera ini tidak ditentukan dan kunci dengan nama yang ditentukan sudah ada, fungsi ini akan mengembalikan NTE_EXISTS.
NCRYPT_REQUIRE_VBS_FLAG Menunjukkan kunci harus dilindungi dengan keamanan berbasis Virtualisasi (VBS). Secara default, ini membuat kunci persisten cross-boot yang disimpan pada disk yang bertahan di seluruh siklus reboot.

Operasi akan gagal jika VBS tidak tersedia. (*Lihat Keterangan)
NCRYPT_PREFER_VBS_FLAG Menunjukkan kunci harus dilindungi dengan keamanan berbasis Virtualisasi (VBS). Secara default, ini membuat kunci persisten cross-boot yang disimpan pada disk yang bertahan di seluruh siklus reboot

Operasi akan menghasilkan kunci yang terisolasi perangkat lunak jika VBS tidak tersedia. (*Lihat Keterangan)
NCRYPT_USE_PER_BOOT_KEY_FLAG Bendera tambahan yang dapat digunakan bersama dengan NCRYPT_REQUIRE_VBS_FLAG atau NCRYPT_PREFER_VBS_FLAG. Menginstruksikan keamanan berbasis Virtualisasi (VBS) untuk melindungi kunci klien dengan kunci per boot yang disimpan dalam disk tetapi tidak dapat digunakan kembali di seluruh siklus boot. (*Lihat Keterangan)

Mengembalikan nilai

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

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

Menampilkan kode Deskripsi
ERROR_SUCCESS Fungsi berhasil.
NTE_BAD_FLAGS Parameter dwFlags berisi nilai yang tidak valid.
NTE_EXISTS Kunci dengan nama yang ditentukan sudah ada dan NCRYPT_OVERWRITE_KEY_FLAG tidak ditentukan.
NTE_INVALID_HANDLE Parameter hProvider tidak valid.
NTE_INVALID_PARAMETER Satu atau beberapa parameter tidak valid.
NTE_NO_MEMORY Terjadi kegagalan alokasi memori.
NTE_VBS_UNAVAILABLE VBS tidak tersedia.

Keterangan

Penting

Informasi mengenai bendera VBS berkaitan dengan produk prarilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Jika Anda membuat pasangan kunci RSA, Anda juga dapat menyimpan kunci dalam penyimpanan warisan sehingga dapat digunakan dengan CryptoAPI dengan meneruskan bendera NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG ke fungsi NCryptFinalizeKey saat kunci diselesaikan.

Layanan tidak boleh memanggil fungsi ini dari Fungsi StartService-nya. Jika layanan memanggil fungsi ini dari fungsi StartService-nya, kebuntuan dapat terjadi, dan layanan mungkin berhenti merespons.

Persyaratan perangkat keras tambahan untuk kunci VBS

Meskipun Anda mungkin memiliki OS yang sesuai yang diinstal pada komputer Anda, persyaratan perangkat keras tambahan berikut harus dipenuhi untuk menggunakan VBS untuk menghasilkan dan melindungi kunci.

  • VBS diaktifkan (lihat Keamanan berbasis virtualisasi (VBS))
  • TPM diaktifkan
    • Untuk lingkungan bare-metal, TPM 2.0 diperlukan.
    • Untuk lingkungan VM, vTPM (Virtual TPM) didukung.
  • BIOS harus ditingkatkan ke UEFI dengan profil SecureBoot

Untuk informasi selengkapnya tentang persyaratan perangkat keras:

  • VBS memiliki beberapa persyaratan perangkat keras untuk dijalankan, termasuk Hyper-V (hypervisor Windows), arsitektur 64 bit, dan dukungan IOMMU. Daftar lengkap persyaratan perangkat keras VBS dapat ditemukan di sini.
  • Persyaratan untuk perangkat yang sangat aman dapat ditemukan di sini.

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 ncrypt.h
Pustaka Ncrypt.lib
DLL Ncrypt.dll

Lihat juga

NCryptDeleteKey

NCryptFinalizeKey

NCryptImportKey