Fungsi NCryptImportKey (ncrypt.h)
Fungsi NCryptImportKey mengimpor kunci Cryptography API: Next Generation (CNG) dari BLOB memori.
Sintaks
SECURITY_STATUS NCryptImportKey(
[in] NCRYPT_PROV_HANDLE hProvider,
[in, optional] NCRYPT_KEY_HANDLE hImportKey,
[in] LPCWSTR pszBlobType,
[in, optional] NCryptBufferDesc *pParameterList,
[out] NCRYPT_KEY_HANDLE *phKey,
[in] PBYTE pbData,
[in] DWORD cbData,
[in] DWORD dwFlags
);
Parameter
[in] hProvider
Handel penyedia penyimpanan utama.
[in, optional] hImportKey
Handel kunci kriptografi tempat data kunci dalam BLOB kunci yang diimpor dienkripsi. Ini harus merupakan handel ke kunci yang sama yang diteruskan dalam parameter hExportKey dari fungsi NCryptExportKey . Jika parameter ini NULL, BLOB kunci diasumsikan tidak dienkripsi.
[in] pszBlobType
String Unicode yang dihentikan null yang berisi pengidentifikasi yang menentukan format BLOB kunci. Format ini khusus untuk penyedia penyimpanan kunci tertentu. Untuk format BLOB yang didukung oleh penyedia Microsoft, lihat Keterangan.
[in, optional] pParameterList
Alamat struktur NCryptBufferDesc yang menunjuk ke array buffer yang berisi informasi parameter untuk kunci.
[out] phKey
Alamat variabel NCRYPT_KEY_HANDLE yang menerima handel kunci. Setelah Anda selesai menggunakan handel ini, lepaskan dengan meneruskannya ke fungsi NCryptFreeObject .
[in] pbData
Alamat buffer yang berisi BLOB kunci yang akan diimpor. Parameter cbData berisi ukuran buffer ini.
[in] cbData
Ukuran, dalam byte, dari penyangga pbData .
[in] dwFlags
Bendera yang mengubah perilaku fungsi. Ini bisa menjadi nol atau kombinasi dari satu atau beberapa nilai berikut. Kumpulan bendera yang valid khusus untuk setiap penyedia penyimpanan kunci.
| Nilai | Makna |
|---|---|
| NCRYPT_SILENT_FLAG | Meminta agar penyedia layanan utama (KSP) tidak menampilkan antarmuka pengguna apa pun. Jika penyedia harus menampilkan UI untuk beroperasi, panggilan gagal dan KSP harus mengatur kode kesalahan NTE_SILENT_CONTEXT sebagai kesalahan terakhir. |
| 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. |
| NTE_VBS_CANNOT_DECRYPT_KEY | Operasi dekripsi gagal VBS. |
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.
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.
Bagian berikut menjelaskan perilaku khusus untuk penyedia penyimpanan kunci Microsoft:
- KSP Perangkat Lunak Microsoft
- KSP Kartu Pintar Microsoft
KSP Perangkat Lunak Microsoft
Konstanta berikut didukung oleh KSP perangkat lunak Microsoft untuk parameter pszBlobType .
Jika nama kunci tidak disediakan, KSP Perangkat Lunak Microsoft memperlakukan kunci sebagai sementara dan tidak menyimpannya secara terus-menerus. Untuk jenis NCRYPT_OPAQUETRANSPORT_BLOB , nama kunci disimpan dalam BLOB saat diekspor. Untuk format BLOB lainnya, nama dapat disediakan dalam parameter buffer NCRYPTBUFFER_PKCS_KEY_NAME dalam parameter pParameterList .
Pada Windows Server 2008 dan Windows Vista, hanya kunci yang diimpor sebagai Blob amplop PKCS #7 (NCRYPT_PKCS7_ENVELOPE_BLOB) atau PKCS #8 blob kunci privat (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) yang dapat dipertahankan dengan menggunakan metode di atas. Untuk mempertahankan kunci yang diimpor melalui jenis BLOB lain pada platform ini, gunakan metode yang didokumentasikan dalam Impor dan Ekspor Kunci.
Bendera berikut didukung oleh KSP ini.
| Istilah | Deskripsi |
|---|---|
| NCRYPT_NO_KEY_VALIDATION | Jangan validasi bagian publik dari pasangan kunci. Bendera ini hanya berlaku untuk pasangan kunci publik/privat. |
| NCRYPT_DO_NOT_FINALIZE_FLAG | Jangan menyelesaikan kunci. Opsi ini berguna ketika Anda perlu menambahkan atau memodifikasi properti kunci setelah mengimpornya. Anda harus menyelesaikan kunci sebelum dapat digunakan dengan meneruskan handel kunci ke fungsi NCryptFinalizeKey . Bendera ini didukung untuk kunci privat PKCS #7 dan PKCS #8 tetapi bukan kunci publik. |
| 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_WRITE_KEY_TO_LEGACY_STORE_FLAG | Simpan juga kunci dalam penyimpanan warisan. Ini memungkinkan kunci untuk digunakan dengan CryptoAPI. Bendera ini hanya berlaku untuk kunci RSA. |
KSP Kartu Pintar Microsoft
Kumpulan format dan bendera BLOB utama yang didukung oleh KSP ini identik dengan set yang didukung oleh KSP Perangkat Lunak Microsoft.
Pada Windows Server 2008 dan Windows Vista, KSP Kartu Pintar Microsoft mengimpor semua kunci ke dalam KSP Perangkat Lunak Microsoft. Dengan demikian, kunci tidak dapat dipertahankan ke kartu pintar dengan menggunakan API ini, dan panduan di bagian di atas berlaku ketika mencoba mempertahankan kunci dalam KSP Perangkat Lunak Microsoft.
Pada Windows Server 2008 R2 dan Windows 7, Penyedia Penyimpanan Kunci Kartu Pintar Microsoft dapat mengimpor kunci privat ke kartu pintar, asalkan kondisi berikut terpenuhi:
- Nama kontainer kunci pada kartu valid.
- Mengimpor kunci privat didukung oleh kartu pintar.
- Dua kunci registri berikut diatur ke DWORD dari
0x1:- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport
Jika nama kontainer kunci adalah NULL, KSP Kartu Pintar Microsoft memperlakukan kunci sebagai sementara dan mengimpornya ke KSP Perangkat Lunak Microsoft.
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
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk