Fungsi CryptAcquireCertificatePrivateKey (wincrypt.h)

Artikel
27/08/2023

Fungsi CryptAcquireCertificatePrivateKey mendapatkan kunci privat untuk sertifikat. Fungsi ini digunakan untuk mendapatkan akses ke kunci privat pengguna saat sertifikat pengguna tersedia, tetapi handel kontainer kunci pengguna tidak tersedia. Fungsi ini hanya dapat digunakan oleh pemilik kunci privat dan bukan oleh pengguna lain.

Jika handel CSP dan kontainer kunci yang berisi kunci privat pengguna tersedia, fungsi CryptGetUserKey harus digunakan sebagai gantinya.

Sintaks

BOOL CryptAcquireCertificatePrivateKey(
  [in]           PCCERT_CONTEXT                  pCert,
  [in]           DWORD                           dwFlags,
  [in, optional] void                            *pvParameters,
  [out]          HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey,
  [out]          DWORD                           *pdwKeySpec,
  [out]          BOOL                            *pfCallerFreeProvOrNCryptKey
);

Parameter

[in] pCert

Alamat struktur CERT_CONTEXT yang berisi konteks sertifikat tempat kunci privat akan diperoleh.

[in] dwFlags

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

Nilai	Makna
CRYPT_ACQUIRE_CACHE_FLAG	Jika handel sudah diperoleh dan di-cache, handel yang sama akan dikembalikan. Jika tidak, handel baru diperoleh dan di-cache dengan menggunakan properti CERT_KEY_CONTEXT_PROP_ID sertifikat. Ketika bendera ini diatur, parameter pfCallerFreeProvOrNCryptKey menerima FALSE dan aplikasi panggilan tidak boleh melepaskan handel. Handel dikosongkan ketika konteks sertifikat dikosongkan; namun, Anda harus mempertahankan konteks sertifikat yang direferensikan oleh parameter pCert selama kunci sedang digunakan, jika tidak, operasi yang mengandalkan kunci akan gagal.
CRYPT_ACQUIRE_COMPARE_KEY_FLAG	Kunci publik dalam sertifikat dibandingkan dengan kunci umum yang dikembalikan oleh penyedia layanan kriptografi (CSP). Jika kunci tidak cocok, operasi akuisisi gagal dan kode kesalahan terakhir diatur ke NTE_BAD_PUBLIC_KEY. Jika handel yang di-cache dikembalikan, tidak ada perbandingan yang dibuat.
CRYPT_ACQUIRE_NO_HEALING	Fungsi ini tidak akan mencoba membuat ulang properti CERT_KEY_PROV_INFO_PROP_ID dalam konteks sertifikat jika properti ini tidak dapat diambil.
CRYPT_ACQUIRE_SILENT_FLAG	CSP tidak boleh menampilkan antarmuka pengguna (UI) apa pun untuk konteks ini. Jika CSP harus menampilkan UI untuk beroperasi, panggilan gagal dan kode kesalahan NTE_SILENT_CONTEXT diatur sebagai kesalahan terakhir.
CRYPT_ACQUIRE_USE_PROV_INFO_FLAG	Menggunakan properti CERT_KEY_PROV_INFO_PROP_ID sertifikat untuk menentukan apakah penembolokan harus dilakukan. Untuk informasi selengkapnya tentang properti CERT_KEY_PROV_INFO_PROP_ID , lihat CertSetCertificateContextProperty. Fungsi ini hanya akan menggunakan penembolokan jika selama panggilan sebelumnya, anggota dwFlags dari struktur CRYPT_KEY_PROV_INFO yang terkandung CERT_SET_KEY_CONTEXT_PROP.
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG	Setiap UI yang diperlukan oleh CSP atau KSP akan menjadi anak dari HWND yang disediakan dalam parameter pvParameters . Untuk kunci CSP, menggunakan bendera ini akan menyebabkan fungsi CryptSetProvParam dengan bendera PP_CLIENT_HWND menggunakan HWND ini dipanggil dengan NULL untuk HCRYPTPROV. Untuk kunci KSP, menggunakan bendera ini akan menyebabkan fungsi NCryptSetProperty dengan bendera NCRYPT_WINDOW_HANDLE_PROPERTY dipanggil menggunakan HWND. Jangan gunakan bendera ini dengan CRYPT_ACQUIRE_SILENT_FLAG.

Bendera berikut menentukan teknologi mana yang digunakan untuk mendapatkan kunci. Jika tidak ada bendera ini, fungsi ini hanya akan mencoba untuk mendapatkan kunci dengan menggunakan CryptoAPI.

Windows Server 2003 dan Windows XP: Bendera ini tidak didukung.

Nilai	Makna
CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG	Fungsi ini akan mencoba untuk mendapatkan kunci dengan menggunakan CryptoAPI. Jika gagal, fungsi ini akan mencoba mendapatkan kunci dengan menggunakan Cryptography API: Next Generation (CNG). Variabel pdwKeySpec menerima bendera CERT_NCRYPT_KEY_SPEC jika CNG digunakan untuk mendapatkan kunci.
CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG	Fungsi ini hanya akan mencoba untuk mendapatkan kunci dengan menggunakan CNG dan tidak akan menggunakan CryptoAPI untuk mendapatkan kunci. Variabel pdwKeySpec menerima bendera CERT_NCRYPT_KEY_SPEC jika CNG digunakan untuk mendapatkan kunci.
CRYPT_ACQUIRE_PREFER_NCRYPT_KEY_FLAG	Fungsi ini akan mencoba mendapatkan kunci dengan menggunakan CNG. Jika gagal, fungsi ini akan mencoba mendapatkan kunci dengan menggunakan CryptoAPI. Variabel pdwKeySpec menerima bendera CERT_NCRYPT_KEY_SPEC jika CNG digunakan untuk mendapatkan kunci. Catatan CryptoAPI tidak mendukung algoritma asimetris CNG Diffie-Hellman atau DSA. CryptoAPI hanya mendukung kunci umum Diffie-Hellman dan DSA melalui CSP warisan. Jika bendera ini diatur untuk sertifikat yang berisi kunci umum Diffie-Hellman atau DSA, fungsi ini akan secara implisit mengubah bendera ini menjadi CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG untuk pertama kali mencoba menggunakan CryptoAPI untuk mendapatkan kunci.

[in, optional] pvParameters

Jika CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG diatur, maka ini adalah alamat HWND. Jika CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG tidak diatur, maka parameter ini harus NULL.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Parameter ini diberi nama pvReserved dan dicadangkan untuk digunakan di masa mendatang dan harus NULL.

[out] phCryptProvOrNCryptKey

Alamat variabel HCRYPTPROV_OR_NCRYPT_KEY_HANDLE yang menerima handel penyedia CryptoAPI atau kunci CNG. Jika variabel pdwKeySpec menerima bendera CERT_NCRYPT_KEY_SPEC , ini adalah handel kunci CNG jenis NCRYPT_KEY_HANDLE; jika tidak, ini adalah handel penyedia CryptoAPI dari jenis HCRYPTPROV.

Untuk informasi selengkapnya tentang kapan dan cara merilis handel ini, lihat deskripsi parameter pfCallerFreeProvOrNCryptKey .

[out] pdwKeySpec

Alamat variabel DWORD yang menerima informasi tambahan tentang kunci. Ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
AT_KEYEXCHANGE	Pasangan kunci adalah pasangan pertukaran kunci.
AT_SIGNATURE	Pasangan kunci adalah pasangan tanda tangan.
CERT_NCRYPT_KEY_SPEC	Kuncinya adalah kunci CNG. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.

[out] pfCallerFreeProvOrNCryptKey

Alamat variabel BOOL yang menerima nilai yang menunjukkan apakah pemanggil harus membebaskan handel yang dikembalikan dalam variabel phCryptProvOrNCryptKey . Ini menerima FALSE jika salah satu hal berikut ini benar:

Akuisisi atau perbandingan kunci publik gagal.
Parameter dwFlags berisi bendera CRYPT_ACQUIRE_CACHE_FLAG .
Parameter dwFlags berisi bendera CRYPT_ACQUIRE_USE_PROV_INFO_FLAG , properti konteks sertifikat diatur ke CERT_KEY_PROV_INFO_PROP_ID dengan struktur CRYPT_KEY_PROV_INFO , dan anggota dwFlags dari struktur CRYPT_KEY_PROV_INFO diatur ke CERT_SET_KEY_CONTEXT_PROP_ID.

Jika variabel ini menerima FALSE, aplikasi panggilan tidak boleh merilis handel yang dikembalikan dalam variabel phCryptProvOrNCryptKey . Handel akan dirilis pada tindakan gratis terakhir dari konteks sertifikat.

Jika variabel ini menerima TRUE, pemanggil bertanggung jawab untuk merilis handel yang dikembalikan dalam variabel phCryptProvOrNCryptKey . Jika variabel pdwKeySpec menerima nilai CERT_NCRYPT_KEY_SPEC , handel harus dirilis dengan meneruskannya ke fungsi NCryptFreeObject ; jika tidak, handel dirilis dengan meneruskannya ke fungsi CryptReleaseContext .

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).

Jika fungsi gagal, nilai yang dikembalikan adalah nol (FALSE). Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Salah satu kemungkinan kode kesalahan adalah sebagai berikut.

Menampilkan kode	Deskripsi
NTE_BAD_PUBLIC_KEY	Kunci publik dalam sertifikat tidak cocok dengan kunci umum yang dikembalikan oleh CSP. Kode kesalahan ini dikembalikan jika CRYPT_ACQUIRE_COMPARE_KEY_FLAG diatur dan kunci umum dalam sertifikat tidak cocok dengan kunci publik yang dikembalikan oleh penyedia kriptografi.
NTE_SILENT_CONTEXT	Parameter dwFlags berisi bendera CRYPT_ACQUIRE_SILENT_FLAG dan CSP tidak dapat melanjutkan operasi tanpa menampilkan antarmuka pengguna.

Keterangan

Ketika CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG diatur, pemanggil harus memastikan HWND valid. Jika HWND tidak lagi valid, untuk CSP pemanggil harus memanggil CryptSetProvParam menggunakan bendera PP_CLIENT_HWND dengan NULL untuk HWND dan NULL untuk HCRYPTPROV. Untuk KSP, pemanggil harus mengatur NCRYPT_WINDOW_HANDLE_PROPERTY kunci ncrypt menjadi NULL. Saat bendera CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG diatur untuk KSP, NCRYPT_WINDOW_HANDLE_PROPERTY diatur pada penyedia penyimpanan dan kunci. Jika kedua panggilan gagal, maka fungsi gagal. Jika hanya satu gagal, fungsi berhasil. Perhatikan bahwa mengatur HWND ke NULL secara efektif menghapus HWND dari HCRYPTPROV atau kunci ncrypt.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Mengirim dan Menerima Pesan Yang Ditandatangani dan Terenkripsi.

Persyaratan


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