Fungsi CertVerifyCertificateChainPolicy (wincrypt.h)

Artikel
08/27/2023

Fungsi CertVerifyCertificateChainPolicy memeriksa rantai sertifikat untuk memverifikasi validitasnya, termasuk kepatuhannya dengan kriteria kebijakan validitas yang ditentukan.

Sintaks

BOOL CertVerifyCertificateChainPolicy(
  [in]      LPCSTR                    pszPolicyOID,
  [in]      PCCERT_CHAIN_CONTEXT      pChainContext,
  [in]      PCERT_CHAIN_POLICY_PARA   pPolicyPara,
  [in, out] PCERT_CHAIN_POLICY_STATUS pPolicyStatus
);

Parameter

[in] pszPolicyOID

Struktur kebijakan rantai verifikasi yang telah ditentukan sebelumnya saat ini tercantum dalam tabel berikut.

Nilai	Makna
CERT_CHAIN_POLICY_BASE (LPCSTR) 1	Menerapkan pemeriksaan verifikasi kebijakan rantai dasar. Anggota dwFlags dari struktur yang diarahkan oleh pPolicyPara dapat diatur untuk mengubah perilaku pemeriksaan kebijakan default.
CERT_CHAIN_POLICY_AUTHENTICODE (LPCSTR) 2	Menerapkan pemeriksaan verifikasi kebijakan rantai Authenticode. Anggota pvExtraPolicyPara dari struktur yang diacu oleh pPolicyPara dapat diatur untuk menunjuk ke struktur AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA . Anggota pvExtraPolicyStatus dari struktur yang diacu oleh pPolicyStatus dapat diatur untuk menunjuk ke struktur AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS .
CERT_CHAIN_POLICY_AUTHENTICODE_TS (LPCSTR) 3	Menerapkan pemeriksaan verifikasi kebijakan rantai Stempel Waktu Authenticode. Anggota pvExtraPolicyPara dari struktur data yang ditunjukkan oleh pPolicyPara dapat diatur untuk menunjuk ke struktur AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA . Anggota pvExtraPolicyStatus dari struktur data yang diacu oleh pPolicyStatus tidak digunakan dan harus diatur ke NULL
CERT_CHAIN_POLICY_SSL (LPCSTR) 4	Menerapkan pemeriksaan verifikasi kebijakan rantai klien/server SSL. Anggota pvExtraPolicyPara dalam struktur data yang diacu oleh pPolicyPara dapat diatur untuk menunjuk ke struktur SSL_EXTRA_CERT_CHAIN_POLICY_PARA yang diinisialisasi dengan kriteria kebijakan tambahan. Catatan Untuk membedakan antara sertifikat otorisasi server dan klien, panggilan ke fungsi CertGetCertificateChain untuk mendapatkan konteks rantai harus menentukan jenis sertifikat dengan mengatur penggunaan yang diharapkan. Atur penggunaan yang diharapkan dengan mengatur anggota RequestedUsage dari struktur CERT_CHAIN_PARA yang diteruskan dalam parameter input pChainPara dari fungsi CertGetCertificateChain .
CERT_CHAIN_POLICY_BASIC_CONSTRAINTS (LPCSTR) 5	Menerapkan kebijakan rantai batasan dasar. Melakukan iterasi melalui semua sertifikat dalam rantai yang memeriksa ekstensi szOID_BASIC_CONSTRAINTS atau szOID_BASIC_CONSTRAINTS2. Jika tidak ada ekstensi, sertifikat diasumsikan memiliki kebijakan yang valid. Jika tidak, untuk elemen sertifikat pertama, memeriksa apakah cocok dengan CA_FLAG yang diharapkan atau END_ENTITY_FLAG yang ditentukan dalam anggota dwFlags dari struktur CERT_CHAIN_POLICY_PARA yang ditunjukkan oleh parameter pPolicyPara . Jika tidak ada atau kedua bendera yang diatur, maka, elemen pertama dapat berupa CA atau END_ENTITY. Semua elemen lain harus menjadi otoritas sertifikasi (CA). Jika PathLenConstraint ada dalam ekstensi, pathLenConstraint akan diperiksa. Elemen pertama dalam rantai sederhana yang tersisa (yaitu, sertifikat yang digunakan untuk menandatangani CTL) diperiksa menjadi END_ENTITY. Jika verifikasi ini gagal, dwError akan diatur ke TRUST_E_BASIC_CONSTRAINTS.
CERT_CHAIN_POLICY_NT_AUTH (LPCSTR) 6	Menerapkan kebijakan rantai Autentikasi Windows NT, yang terdiri dari tiga verifikasi rantai yang berbeda dalam urutan berikut: CERT_CHAIN_POLICY_BASE—Menerapkan pemeriksaan verifikasi kebijakan rantai dasar. LOWORD dwFlags dapat diatur di pPolicyPara untuk mengubah perilaku pemeriksaan kebijakan default. Untuk informasi selengkapnya, lihat CERT_CHAIN_POLICY_BASE. CERT_CHAIN_POLICY_BASIC_CONSTRAINTS—Menerapkan kebijakan rantai batasan dasar. HIWORD dwFlags dapat diatur untuk menentukan apakah elemen pertama harus berupa CA atau END_ENTITY. Untuk informasi selengkapnya, lihat CERT_CHAIN_POLICY_BASIC_CONSTRAINTS. Memeriksa apakah elemen kedua dalam rantai, CA yang mengeluarkan sertifikat akhir, adalah CA tepercaya untuk Autentikasi Windows NT. CA dianggap tepercaya jika ada di penyimpanan registri sistem "NTAuth" yang ditemukan di lokasi penyimpanan CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE. Jika verifikasi ini gagal, CA tidak tepercaya, dan dwError diatur ke CERT_E_UNTRUSTEDCA. Jika CERT_PROT_ROOT_DISABLE_NT_AUTH_REQUIRED_FLAG diatur dalam nilai Bendera dari kebijakan HKEY_LOCAL_MACHINE subkuntah ProtectedRoots , yang ditentukan oleh CERT_PROT_ROOT_FLAGS_REGPATH dan pemeriksaan di atas gagal, rantai diperiksa untuk CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS diatur dalam dwInfoStatus. Ini diatur jika ada batasan nama yang valid untuk semua namespace termasuk UPN. Jika rantai tidak memiliki status info ini yang diatur, dwError diatur ke CERT_E_UNTRUSTEDCA.
CERT_CHAIN_POLICY_MICROSOFT_ROOT (LPCSTR) 7	Memeriksa elemen terakhir dari rantai sederhana pertama untuk kunci publik akar Microsoft. Jika elemen tersebut tidak berisi kunci publik akar Microsoft, anggota dwError dari struktur CERT_CHAIN_POLICY_STATUS yang diarahkan oleh parameter pPolicyStatus diatur ke CERT_E_UNTRUSTEDROOT. Anggota dwFlags dari struktur CERT_CHAIN_POLICY_PARA yang diarahkan oleh parameter pPolicyStatus dapat berisi bendera MICROSOFT_ROOT_CERT_CHAIN_POLICY_CHECK_APPLICATION_ROOT_FLAG , yang menyebabkan fungsi ini memeriksa akar aplikasi Microsoft "Microsoft Root Certificate Authority 2011". Anggota dwFlags dari struktur CERT_CHAIN_POLICY_PARA yang ditunjukkan oleh parameter pPolicyPara dapat berisi bendera MICROSOFT_ROOT_CERT_CHAIN_POLICY_ENABLE_TEST_ROOT_FLAG , yang menyebabkan fungsi ini juga memeriksa akar pengujian Microsoft. CatatanPengidentifikasi objek kebijakan (OID) ini tidak melakukan pemeriksaan verifikasi kebijakan dengan sendirinya, itu dimaksudkan untuk digunakan bersama dengan kebijakan lain.
CERT_CHAIN_POLICY_EV (LPCSTR) 8	Menentukan bahwa validasi sertifikat yang diperluas dilakukan. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
CERT_CHAIN_POLICY_SSL_F12 (LPCSTR) 9	Memeriksa apakah ada sertifikat dalam rantai yang memiliki kripto yang lemah atau jika kepatuhan sertifikat akar pihak ketiga dan memberikan string kesalahan. Anggota pvExtraPolicyStatus dari struktur CERT_CHAIN_POLICY_STATUS yang ditunjukkan oleh parameter pPolicyStatus harus menunjuk ke SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS, yang diperbarui dengan hasil pemeriksaan kepatuhan kripto dan program root yang lemah. Sebelum memanggil, anggota cbSize dari struktur CERT_CHAIN_POLICY_STATUS yang ditujukkan oleh parameter pPolicyStatus harus diatur ke nilai yang lebih besar dari atau sama dengan sizeof(SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS). Anggota dwError dalam struktur CERT_CHAIN_POLICY_STATUS yang ditunjukkan oleh parameter pPolicyStatus akan diatur ke TRUST_E_CERT_SIGNATURE untuk potensi kripto lemah dan diatur ke CERT_E_UNTRUSTEDROOT untuk Akar Pihak Ketiga yang tidak mematuhi Program Akar Microsoft. Windows 10, versi 1607, Windows Server 2016, Windows 10, versi 1511 dengan KB3172985, Windows 10 RTM dengan KB3163912, Windows 8.1 dan Windows Server 2012 R2 dengan KB3163912, dan Windows 7 dengan SP1 dan Windows Server 2008 R2 SP1 dengan KB3161029

[in] pChainContext

Penunjuk ke struktur CERT_CHAIN_CONTEXT yang berisi rantai yang akan diverifikasi.

[in] pPolicyPara

Penunjuk ke struktur CERT_CHAIN_POLICY_PARA yang menyediakan kriteria verifikasi kebijakan untuk rantai. Anggota dwFlags dari struktur tersebut dapat diatur untuk mengubah perilaku pemeriksaan kebijakan default.

Selain itu, parameter khusus kebijakan juga dapat diteruskan di anggota struktur pvExtraPolicyPara .

[in, out] pPolicyStatus

Penunjuk ke struktur CERT_CHAIN_POLICY_STATUS tempat informasi status pada rantai dikembalikan. Status tambahan khusus OID dapat dikembalikan di anggota pvExtraPolicyStatus dari struktur ini.

Mengembalikan nilai

Nilai pengembalian menunjukkan apakah fungsi dapat memeriksa kebijakan, itu tidak menunjukkan apakah pemeriksaan kebijakan gagal atau lulus.

Jika rantai dapat diverifikasi untuk kebijakan yang ditentukan, TRUE dikembalikan dan anggota dwError dari pPolicyStatus diperbarui. dwError 0 (ERROR_SUCCESS atau S_OK) menunjukkan rantai memenuhi kebijakan yang ditentukan.

Jika rantai tidak dapat divalidasi, nilai yang dikembalikan adalah TRUE dan Anda perlu memverifikasi parameter pPolicyStatus untuk kesalahan aktual.

Nilai FALSE menunjukkan bahwa fungsi tidak dapat memeriksa kebijakan.

Keterangan

Anggota dwError dari struktur CERT_CHAIN_POLICY_STATUS yang ditunjukkan oleh pPolicyStatus dapat diterapkan ke elemen rantai tunggal, ke rantai sederhana, atau ke seluruh konteks rantai. Jika dwError berlaku untuk seluruh konteks rantai, baik anggota lChainIndex dan lElementIndex dari struktur CERT_CHAIN_POLICY_STATUS diatur ke –1. Jika dwError berlaku untuk rantai sederhana lengkap, lElementIndex diatur ke –1 dan lChainIndex diatur ke indeks rantai pertama yang memiliki kesalahan. Jika dwError berlaku untuk elemen sertifikat tunggal, indeks lChainIndex dan lElementIndex sertifikat pertama yang memiliki kesalahan.

Untuk mendapatkan elemen sertifikat, gunakan sintaks ini:

pChainContext->rgpChain[lChainIndex]->rgpElement[lElementIndex];

Gunakan fungsi CertGetCertificateChain untuk mengaktifkan dan melakukan pemeriksaan pencabutan sertifikat. Fungsi CertVerifyCertificateChainPolicy tidak memeriksa apakah sertifikat dalam rantai sertifikat dicabut.

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