Fungsi PFXImportCertStore (wincrypt.h)

  • Artikel

Fungsi PFXImportCertStore mengimpor BLOB PFX dan mengembalikan handel penyimpanan yang berisi sertifikat dan kunci privat terkait.

Sintaks

HCERTSTORE PFXImportCertStore(
  [in] CRYPT_DATA_BLOB *pPFX,
  [in] LPCWSTR         szPassword,
  [in] DWORD           dwFlags
);

Parameter

[in] pPFX

Penunjuk ke struktur CRYPT_DATA_BLOB yang berisi paket PFX dengan sertifikat dan kunci yang diekspor dan dienkripsi.

[in] szPassword

Kata sandi string yang digunakan untuk mendekripsi dan memverifikasi paket PFX. Apakah diatur ke string panjang yang lebih besar dari nol atau diatur ke string kosong atau ke NULL, nilai ini harus sama persis dengan nilai yang digunakan untuk mengenkripsi paket.

Dimulai dengan Windows 8 dan Windows Server 2012, jika paket PFX dibuat dalam fungsi PFXExportCertStoreEx dengan menggunakan bendera PKCS12_PROTECT_TO_DOMAIN_SIDS, fungsi PFXImportCertStore mencoba mendekripsi kata sandi dengan menggunakan perwakilan Direktori Aktif (AD) yang digunakan untuk mengenkripsinya. Perwakilan AD ditentukan dalam parameter pvPara . Jika parameter szPassword dalam fungsi PFXExportCertStoreEx adalah string kosong atau NULL dan parameter dwFlags diatur ke PKCS12_PROTECT_TO_DOMAIN_SIDS, fungsi tersebut secara acak menghasilkan kata sandi dan mengenkripsinya ke perwakilan AD yang ditentukan dalam parameter pvPara . Dalam hal ini Anda harus mengatur kata sandi ke nilai, string kosong atau NULL, yang digunakan saat paket PFX dibuat. Fungsi PFXImportCertStore akan menggunakan perwakilan AD untuk mendekripsi kata sandi acak, dan kata sandi yang dihasilkan secara acak akan digunakan untuk mendekripsi sertifikat PFX.

Setelah Anda selesai menggunakan kata sandi, bersihkan dari memori dengan memanggil fungsi SecureZeroMemory . Untuk informasi selengkapnya tentang melindungi kata sandi, lihat Menangani Kata Sandi.

[in] dwFlags

Parameter dwFlags dapat menjadi salah satu nilai berikut:

Nilai Makna
CRYPT_EXPORTABLE
0x00000001
 Kunci yang diimpor ditandai sebagai dapat diekspor. Jika bendera ini tidak digunakan, panggilan ke fungsi CryptExportKey dengan handel kunci gagal.
CRYPT_USER_PROTECTED
0x00000002
 Pengguna akan diberi tahu melalui kotak dialog atau metode lain ketika upaya tertentu untuk menggunakan kunci ini dibuat. Perilaku yang tepat ditentukan oleh penyedia layanan kriptografi (CSP) yang digunakan.

Sebelum Internet Explorer 4.0, penyedia layanan kriptografi Microsoft mengabaikan bendera ini. Dimulai dengan Internet Explorer 4.0, penyedia Microsoft mendukung bendera ini.

Jika konteks penyedia dibuka dengan set bendera CRYPT_SILENT, menggunakan bendera ini menyebabkan kegagalan dan kesalahan terakhir diatur ke NTE_SILENT_CONTEXT.
CRYPT_MACHINE_KEYSET
0x00000020
 Kunci privat disimpan di bawah komputer lokal dan bukan di bawah pengguna saat ini.
CRYPT_USER_KEYSET
0x00001000
 Kunci privat disimpan di bawah pengguna saat ini dan bukan di bawah komputer lokal bahkan jika BLOB PFX menentukan bahwa mereka harus masuk ke komputer lokal.
PKCS12_PREFER_CNG_KSP
0x00000100
 Menunjukkan bahwa penyedia penyimpanan kunci CNG (KSP) lebih disukai. Jika CSP ditentukan dalam file PFX, maka CSP digunakan, jika tidak, KSP lebih disukai. Jika CNG KSP tidak tersedia, fungsi PFXImportCertStore akan gagal.

Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
PKCS12_ALWAYS_CNG_KSP
0x00000200
 Menunjukkan bahwa KSP CNG selalu digunakan. Ketika ditentukan, PFXImportCertStore mencoba menggunakan CNG KSP terlepas dari informasi penyedia dalam file PFX. Jika CNG KSP tidak tersedia, impor tidak akan gagal.

Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
 Izinkan penimpaan kunci yang ada. Tentukan bendera ini ketika Anda menemukan skenario di mana Anda harus mengimpor file PFX yang berisi nama kunci yang sudah ada. Misalnya, ketika Anda mengimpor file PFX, ada kemungkinan bahwa kontainer dengan nama yang sama sudah ada karena tidak ada namespace unik untuk kontainer kunci. Jika Anda telah membuat "TestKey" di komputer Anda, dan kemudian Anda mengimpor file PFX yang juga memiliki "TestKey" sebagai kontainer kunci, pengaturan PKCS12_ALLOW_OVERWRITE_KEY memungkinkan kunci ditimpa.

Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
PKCS12_NO_PERSIST_KEY
0x00008000
 Jangan pertahankan kunci. Tentukan bendera ini jika Anda tidak ingin mempertahankan kunci. Misalnya, jika tidak perlu menyimpan kunci setelah verifikasi, maka alih-alih membuat kontainer dan kemudian menghapusnya, Anda dapat menentukan bendera ini untuk segera membuang kunci.
Catatan Jika bendera PKCS12_NO_PERSIST_KEY diatur *bukan*, kunci akan tetap ada di disk. Jika Anda tidak ingin mempertahankan kunci di luar penggunaannya, Anda harus menghapusnya dengan memanggil fungsi CryptAcquireContext dengan bendera CRYPT_DELETEKEYSET yang diatur dalam parameter dwFlags .
Catatan Beberapa pertimbangan lain:

  • Saat menggunakan PKCS12_NO_PERSIST_KEY, properti CERT_KEY_CONTEXT_PROP_ID diatur secara internal pada sertifikat, dan CERT_KEY_CONTEXT_PROP_ID berisi NCRYPT_KEY_HANDLE.

  • Jika PKCS12_NO_PERSIST_KEY tidak digunakan, properti CERT_KEY_PROV_INFO_PROP_ID diatur.

  • Jika sertifikat dengan kunci yang tidak bertahan dirusak ke proses lain, properti CERT_KEY_CONTEXT_PROP_ID tidak akan dinaungi.

  • Agar NO_PERSIST berfungsi, itu harus dalam proses yang sama dan pengguna PCCERT_CONTEXT harus mendukung CERT_KEY_CONTEXT_PROP_ID. Ini biasanya berlaku selama jabat tangan TLS: jika jabat tangan dilakukan secara eksternal ke proses panggilan dalam LSASS.exe, tidak mungkin untuk menggunakan PKCS12_NO_PERSIST_KEY saat berpindah dari proses panggilan ke LSASS (karena NCRYPT_KEY_HANDLE adalah penunjuk ke struktur data dan bukan handel kernel).

 
Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
 Impor semua properti yang diperluas pada sertifikat yang disimpan pada sertifikat ketika diekspor.

Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
0x10000000
 Buka kemasan tetapi jangan pertahankan hasilnya.

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan handel ke penyimpanan sertifikat yang berisi sertifikat yang diimpor, termasuk kunci privat yang tersedia.

Jika fungsi gagal, yaitu, jika parameter kata sandi tidak berisi kecocokan persis dengan kata sandi yang digunakan untuk mengenkripsi paket yang diekspor atau jika ada masalah lain saat mendekode BLOB PFX, fungsi mengembalikan NULL, dan kode kesalahan dapat ditemukan dengan memanggil fungsi GetLastError .

Keterangan

Fungsi PFXImportCertStore membuka penyimpanan sementara. Jika fungsi berhasil, Anda harus menutup handel ke penyimpanan dengan memanggil fungsi CertCloseStore .

Saat Anda mengimpor sertifikat dari paket PFX, nama kontainer CSP/KSP ditentukan dengan menggunakan AttributeId dengan OID 1.3.6.1.4.1.311.17.1 dari PKCS8ShroudedKeyBag SafeBagg [bagId: 1.2.840.113549.1.12.10.1.2] (lihat PKCS #12 untuk detail tentang struktur ASN.1 ini).

  • AttributeId: 1.3.6.1.4.1.311.17.1
  • Nilai: Nama KSP atau nama CSP

Jika AttributeId tidak ada dan bendera PREFER_CNG diteruskan, MS_KEY_STORAGE_PROVIDER dipilih. Jika AttributeId tidak ada dan bendera PREFER_CNG tidak diteruskan, nama penyedia ditentukan berdasarkan algoritma kunci publik (yaitu, algoritma kunci publik ditentukan oleh AlgoritmaIdentifier di PKCS #8):

  • RSA: MS_ENHANCED_PROV_W
  • DSA: MS_DEF_DSS_DH_PROV_W

Demikian pula, spesifikasi kunci ditentukan dengan menggunakan AttributeId dengan OID 2.5.29.15 (szOID_KEY_USAGE) sebagai berikut:

Jika kunci CAPI digunakan:

  • Jika KEY_ENCIPHERMENT atau DATA_ENCIPHERMENT diatur, maka spesifikasi kunci diatur ke AT_KEYEXCHANGE.
  • Jika DIGITAL_SIGNATURE atau CERT_SIGN atau CRL_SIGN diatur, maka spesifikasi kunci diatur ke AT_SIGNATURE.

Jika kunci CNG digunakan:

  • Jika KEY_ENCIPHERMENT atau DATA_ENCIPHERMENT atau ENCIPHER_ONLY atau DECIPHER_ONLY diatur, maka penggunaan kunci ncrypt diatur ke ALLOW_DECRYPT.
  • Jika DIGITAL_SIGNATURE atau CERT_SIGN atau CRL_SIGN diatur, penggunaan kunci ncrypt diatur ke ALLOW_SIGN.
  • Jika KEY_AGREEMENT diatur, maka penggunaan kunci ncrypt diatur ke ALLOW_KEY_AGREEMENT.

Jika AttributeId tidak ada, maka nilai kunci CAPI diatur ke AT_KEYEXCHANGE untuk RSA atau DH dan algoritma ditentukan oleh AlgoritmaIdentifier di PKCS #8; jika tidak, algoritma diatur ke AT_SIGNATURE. Untuk nilai kunci CNG, semua penggunaan kunci ncrypt diatur.

Catatan

Jika nama penyedia yang tidak valid ada dalam paket PFX, atau penyedia kriptografi dasar atau yang ditingkatkan tidak ada dalam kunci registri ini: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, maka pencarian penyedia dilakukan oleh jenis penyedia menggunakan subkunji registri ini: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.

Microsoft hanya mendukung dua algoritma enkripsi/hash untuk mengimpor PFX:

  • TripleDES-SHA1
  • AES256-SHA256

Untuk salah satu algoritma di atas, enkripsi sertifikat bersifat opsional.

Microsoft dapat mengekspor PFX dari penyimpanan sertifikat melalui All Tasks>Yes, export the private key pilihan. Di sana Anda dapat memilih algoritma enkripsi/hash agar sesuai dengan salah satu dari dua pilihan ini.

Anda bisa menggunakan PowerShell untuk mengekspor PFX melalui yang berikut ini:

Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]

-CryptoAlgorithmOption menentukan algoritma untuk mengenkripsi kunci privat dalam file PFX. Jika parameter ini tidak ditentukan, defaultnya adalah TripleDES_SHA1. Nilai yang dapat diterima untuk parameter ini adalah:

Nilai Deskripsi
TripleDES_SHA1 Kunci privat akan dienkripsi dalam file PFX menggunakan enkripsi Triple DES.
AES256_SHA256 Kunci privat akan dienkripsi dalam file PFX menggunakan enkripsi AES-256.

OpenSSL mendukung dua algoritma di atas melalui perintah berikut:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe AES-256-CBC -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Perintah berikut setara dengan dua sebelumnya, tetapi tidak mengenkripsi sertifikat:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe NONE -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe NONE -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows XP [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2003 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header wincrypt.h
Pustaka Crypt32.lib
DLL Crypt32.dll

Lihat juga

PFXExportCertStore

PFXExportCertStoreEx