Fungsi CertGetCertificateChain (wincrypt.h)
Fungsi CertGetCertificateChain membangun konteks rantai sertifikat mulai dari sertifikat akhir dan kembali, jika memungkinkan, ke sertifikat akar tepercaya.
Sintaks
BOOL CertGetCertificateChain(
[in, optional] HCERTCHAINENGINE hChainEngine,
[in] PCCERT_CONTEXT pCertContext,
[in, optional] LPFILETIME pTime,
[in] HCERTSTORE hAdditionalStore,
[in] PCERT_CHAIN_PARA pChainPara,
[in] DWORD dwFlags,
[in] LPVOID pvReserved,
[out] PCCERT_CHAIN_CONTEXT *ppChainContext
);
Parameter
[in, optional] hChainEngine
Handel mesin rantai (namespace dan cache) yang akan digunakan. Jika hChainEngine adalah NULL, mesin rantai default, HCCE_CURRENT_USER, digunakan. Parameter ini dapat diatur ke HCCE_LOCAL_MACHINE.
[in] pCertContext
Penunjuk ke CERT_CONTEXT sertifikat akhir, sertifikat yang rantainya sedang dibangun. Konteks sertifikat ini akan menjadi elemen nol indeks dalam rantai sederhana pertama.
[in, optional] pTime
Penunjuk ke variabel FILETIME yang menunjukkan waktu di mana rantai akan divalidasi. Perhatikan bahwa waktu tidak memengaruhi daftar kepercayaan, pencabutan, atau pemeriksaan penyimpanan akar. Waktu sistem saat ini digunakan jika NULL diteruskan ke parameter ini. Kepercayaan pada sertifikat tertentu menjadi akar tepercaya didasarkan pada status penyimpanan akar saat ini dan bukan status penyimpanan akar pada satu waktu yang diteruskan oleh parameter ini. Untuk pencabutan, daftar pencabutan sertifikat (CRL), itu sendiri, harus valid pada saat ini. Nilai parameter ini digunakan untuk menentukan apakah sertifikat yang tercantum dalam CRL telah dicabut.
[in] hAdditionalStore
Handel ke penyimpanan tambahan untuk mencari sertifikat pendukung dan daftar kepercayaan sertifikat (CCL). Parameter ini bisa NULL jika tidak ada penyimpanan tambahan yang akan dicari.
[in] pChainPara
Penunjuk ke struktur CERT_CHAIN_PARA yang mencakup parameter pembangun rantai.
[in] dwFlags
Bendera nilai yang menunjukkan pemrosesan khusus. Parameter ini bisa menjadi kombinasi dari satu atau beberapa bendera berikut.
| Nilai | Makna |
|---|---|
|
Ketika bendera ini diatur, sertifikat akhir di-cache, yang mungkin mempercepat proses pembuatan rantai. Secara default, sertifikat akhir tidak di-cache, dan perlu diverifikasi setiap kali rantai dibangun untuk itu. |
|
Pemeriksaan pencabutan hanya mengakses URL yang di-cache. |
|
Bendera ini digunakan secara internal selama pembuatan rantai untuk sertifikat penanda tangan protokol status sertifikat online (OCSP) untuk mencegah pemeriksaan pencabutan siklik. Selama pembangunan rantai, jika respons OCSP ditandatangani oleh penanda tangan OCSP independen, maka, selain build rantai asli, ada rantai kedua yang dibangun untuk sertifikat penanda tangan OCSP itu sendiri. Bendera ini digunakan selama build rantai kedua ini untuk menghambat sertifikat penanda tangan OCSP independen rekursif. Jika sertifikat penanda tangan berisi ekstensi szOID_PKIX_OCSP_NOCHECK , pemeriksaan pencabutan dilewati untuk sertifikat penanda tangan daun. Pemeriksaan OCSP dan CRL diizinkan.
Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
|
Hanya menggunakan URL yang di-cache dalam membangun rantai sertifikat. Internet dan intranet tidak dicari untuk objek berbasis URL.
Catatan Bendera ini tidak berlaku untuk pemeriksaan pencabutan. Atur CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY untuk hanya menggunakan URL yang di-cache untuk pemeriksaan pencabutan. |
|
Untuk alasan performa, lulus kedua pembuatan rantai hanya mempertimbangkan jalur rantai potensial yang memiliki kualitas lebih besar dari atau sama dengan kualitas tertinggi yang ditentukan selama lulus pertama. Pass pertama hanya mempertimbangkan tanda tangan yang valid, rantai lengkap, dan akar tepercaya untuk menghitung kualitas rantai. Bendera ini dapat diatur untuk menonaktifkan pengoptimalan ini dan mempertimbangkan semua jalur rantai potensial selama pass kedua. |
|
Bendera ini tidak didukung. Sertifikat di penyimpanan "Saya" tidak pernah dipertimbangkan untuk kepercayaan serekan. |
|
Sertifikat entitas akhir di penyimpanan "TrustedPeople" dipercaya tanpa melakukan pembangunan rantai apa pun. Fungsi ini tidak mengatur CERT_TRUST_IS_PARTIAL_CHAIN atau CERT_TRUST_IS_UNTRUSTED_ROOTbit anggota dwErrorStatus dari parameter ppChainContext . Windows Server 2003 Windows XP : Bendera ini tidak didukung. |
|
Mengatur bendera ini menunjukkan pemanggil ingin memilih pemeriksaan tanda tangan yang lemah.
Bendera ini tersedia dalam pembaruan rollup untuk setiap OS yang dimulai dengan Windows 7 dan Windows Server 2008 R2. |
|
Defaultnya adalah hanya mengembalikan jalur rantai kualitas tertinggi. Mengatur bendera ini akan mengembalikan rantai kualitas yang lebih rendah. Ini dikembalikan dalam bidang cLowerQualityChainContext dan rgpLowerQualityChainContext dari konteks rantai. |
|
Mengatur bendera ini menghambat pembaruan otomatis akar pihak ketiga dari Windows Update Web Server. |
|
Saat Anda mengatur CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT dan Anda juga menentukan nilai untuk anggota dwUrlRetrievalTimeout dari struktur CERT_CHAIN_PARA , nilai yang Anda tentukan di dwUrlRetrievalTimeout mewakili batas waktu kumulatif di semua pengambilan URL pencabutan.
Jika Anda mengatur CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT tetapi tidak menentukan nilai dwUrlRetrievalTimeout , batas waktu kumulatif maksimum diatur, secara default, hingga 20 detik. Setiap URL yang diuji akan habis setelah setengah dari sisa saldo kumulatif telah berlalu. Artinya, WAKTU URL pertama habis setelah 10 detik, yang kedua setelah 5 detik, yang ketiga setelah 2,5 detik dan seterusnya sampai URL berhasil, 20 detik telah berlalu, atau tidak ada LAGI URL untuk diuji. Jika Anda tidak mengatur CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, setiap URL pencabutan dalam rantai diberi batas waktu maksimum yang sama dengan nilai yang ditentukan dalam dwUrlRetrievalTimeout. Jika Anda tidak menentukan nilai untuk anggota dwUrlRetrievalTimeout , setiap URL pencabutan diberi batas waktu default maksimum 15 detik. Jika tidak ada URL yang berhasil, nilai batas waktu kumulatif maksimum adalah 15 detik dikalikan dengan jumlah URL dalam rantai. Anda dapat mengatur nilai default dengan menggunakan Kebijakan Grup. |
|
Ketika bendera ini diatur, pTime digunakan sebagai waktu stempel waktu untuk menentukan apakah sertifikat akhir valid. Waktu saat ini juga dapat digunakan untuk menentukan apakah sertifikat akhir tetap valid waktu. Semua otoritas sertifikasi (CA) dan sertifikat akar lainnya dalam rantai diperiksa dengan menggunakan waktu saat ini dan bukan pTime. |
|
Mengatur bendera ini secara eksplisit menonaktifkan pengambilan Authority Information Access (AIA). |
Anda juga dapat mengatur bendera pencabutan berikut, tetapi hanya satu bendera dari grup ini yang dapat diatur pada satu waktu.
[in] pvReserved
Parameter ini dicadangkan dan harus NULL.
[out] ppChainContext
Alamat penunjuk ke konteks rantai yang dibuat. Setelah Anda selesai menggunakan konteks rantai, lepaskan rantai dengan memanggil fungsi CertFreeCertificateChain .
Mengembalikan nilai
Jika fungsi berhasil, fungsi mengembalikan bukan nol (TRUE).
Jika fungsi gagal, fungsi akan mengembalikan nol (FALSE). Untuk informasi kesalahan yang diperluas, hubungi GetLastError.
Keterangan
Ketika aplikasi meminta rantai sertifikat, struktur yang dikembalikan dalam bentuk CERT_CHAIN_CONTEXT. Konteks ini berisi array struktur CERT_SIMPLE_CHAIN di mana setiap rantai sederhana beralih dari sertifikat akhir ke sertifikat yang ditandatangani sendiri. Konteks rantai menghubungkan rantai sederhana melalui daftar kepercayaan. Setiap rantai sederhana berisi rantai sertifikat, ringkasan informasi kepercayaan tentang rantai, dan informasi kepercayaan tentang setiap elemen sertifikat dalam rantai.
Keterangan berikut berlaku untuk pemeriksaan tanda tangan yang kuat:
- Anda dapat mengaktifkan pemeriksaan tanda tangan yang kuat untuk fungsi ini dengan mengatur anggota pStrongSignPara dari struktur CERT_CHAIN_PARA yang diarahkan oleh parameter pChainPara .
- Jika sertifikat tanpa tanda tangan yang kuat ditemukan dalam rantai, kesalahan CERT_TRUST_HAS_WEAK_SIGNATURE dan CERT_TRUST_IS_NOT_SIGNATURE_VALID diatur di bidang dwErrorStatus dari struktur CERT_TRUST_STATUS . Parameter ppChainContext menunjuk ke struktur CERT_CHAIN_CONTEXT yang, pada gilirannya, menunjuk ke struktur CERT_TRUST_STATUS .
- Jika rantai ditandatangani dengan kuat, kunci publik di akhir sertifikat diperiksa untuk menentukan apakah rantai memenuhi persyaratan panjang kunci publik minimum untuk tanda tangan yang kuat. Jika kondisi tidak terpenuhi, kesalahan CERT_TRUST_HAS_WEAK_SIGNATURE dan CERT_TRUST_IS_NOT_SIGNATURE_VALID diatur di bidang dwErrorStatus dari struktur CERT_TRUST_STATUS . Untuk menonaktifkan pemeriksaan panjang kunci, atur nilai CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG di anggota dwStrongSignFlags dari struktur CERT_CHAIN_PARA yang diarahkan oleh parameter pChainPara .
- Jika bendera CERT_STRONG_SIGN_ENABLE_CRL_CHECK atau CERT_STRONG_SIGN_ENABLE_OCSP_CHECK diatur dalam struktur CERT_STRONG_SIGN_SERIALIZED_INFO dan respons CRL atau OCSP ditemukan tanpa tanda tangan yang kuat, respons CRL atau OCSP akan diperlakukan offline. Artinya, kesalahan CERT_TRUST_IS_OFFLINE_REVOCATION dan CERT_TRUST_REVOCATION_STATUS_UNKNOWN diatur di bidang dwErrorStatus dari struktur CERT_TRUST_STATUS . Selain itu, anggota dwRevocationResult dari struktur CERT_REVOCATION_INFO diatur ke NTE_BAD_ALGID.
Contoh
Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Membuat Rantai Sertifikat.
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 |
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