Baca dalam bahasa Inggris

Bagikan melalui

Fungsi CertGetCertificateChain (wincrypt.h)

  • Artikel

Fungsi CertGetCertificateChain membangun konteks rantai sertifikat mulai dari sertifikat akhir dan kembali, jika memungkinkan, ke sertifikat akar tepercaya.

Sintaksis

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 hChainEngineNULL, mesin rantai default, HCCE_CURRENT_USER, digunakan. Parameter ini dapat diatur ke HCCE_LOCAL_MACHINE.

[in] pCertContext

Penunjuk ke CERT_CONTEXT sertifikat akhir, sertifikat tempat rantai sedang dibangun. Konteks sertifikat ini akan menjadi elemen nol indeks dalam rantai sederhana pertama.

[in, optional] pTime

Penunjuk ke variabel FILETIME yang menunjukkan waktu 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 saat ini penyimpanan akar 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 apa pun untuk mencari sertifikat pendukung dan daftar kepercayaan sertifikat (CTL). Parameter ini dapat NULL jika tidak ada penyimpanan tambahan yang akan dicari.

[in] pChainPara

Penunjuk ke struktur CERT_CHAIN_PARA yang mencakup parameter pembangunan rantai.

[in] dwFlags

Bendera nilai yang menunjukkan pemrosesan khusus. Parameter ini bisa menjadi kombinasi dari satu atau beberapa bendera berikut.

Nilai Arti
CERT_CHAIN_CACHE_END_CERT
0x00000001		 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 untuknya.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
0x80000000		 Pemeriksaan pencabutan hanya mengakses URL yang di-cache. Ini akan mencegah pengambilan jaringan CRL atau OCSP untuk sertifikat akhir atau CA. CACHE_ONLY tergantung pada teman di komputer untuk telah mengambil CRL atau OCSP dari jaringan.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT
0x04000000		 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.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
0x00000004		 Hanya menggunakan URL yang di-cache dalam membangun rantai sertifikat. Internet dan intranet tidak dicari untuk objek berbasis URL, seperti kabin CTL, root Pihak Ketiga, dan penerbit AIA. Sebagian besar akar harus berada dalam sumber daya crypt32.dll. Jika tidak, maka pengambilan ini diperlukan untuk mencegah kesalahan pembangunan rantai. Kabin dan akar ini dihosting di server CDN Microsoft berkinerja tinggi.

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. Biasanya, kabin CTL sudah diambil sebelumnya melalui layanan cryptsvc.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 Untuk alasan performa, pass kedua pembuatan rantai hanya mempertimbangkan jalur rantai potensial yang memiliki kualitas lebih besar dari atau sama dengan kualitas tertinggi yang ditentukan selama pass 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.
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800		 Bendera ini tidak didukung. Sertifikat di penyimpanan "Saya" tidak pernah dipertimbangkan untuk kepercayaan serekan.
CERT_CHAIN_ENABLE_PEER_TRUST
0x00000400		 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_ROOTdwErrorStatus bit anggota parameter ppChainContext.

Windows Server 2003 dan Windows XP: Bendera ini tidak didukung.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE
0x00010000		 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.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS
0x00000080		 Defaultnya adalah mengembalikan hanya jalur rantai kualitas tertinggi. Mengatur bendera ini akan mengembalikan rantai kualitas yang lebih rendah. Ini dikembalikan dalam cLowerQualityChainContext dan rgpLowerQualityChainContext bidang konteks rantai.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE
0x00000100		 Mengatur bendera ini menghambat pembaruan otomatis akar pihak ketiga dari Windows Update Web Server.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT
0x08000000		 Saat Anda mengatur CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT dan Anda juga menentukan nilai untuk dwUrlRetrievalTimeout anggota 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 sebagainya 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.
CERT_CHAIN_TIMESTAMP_TIME
0x00000200		 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 lainnya (CA) dan sertifikat akar dalam rantai diperiksa dengan menggunakan waktu saat ini dan tidak pTime.
CERT_CHAIN_DISABLE_AIA
0x00002000		 Mengatur bendera ini secara eksplisit menonaktifkan pengambilan Authority Information Access (AIA). Terkadang server TLS salah dikonfigurasi dan tidak menyertakan sertifikat CA yang benar dalam jabat tangan.

Anda juga dapat mengatur bendera pencabutan berikut, tetapi hanya satu bendera dari grup ini yang dapat diatur pada satu waktu.

Nilai Arti
CERT_CHAIN_REVOCATION_CHECK_END_CERT
0x10000000		 Pemeriksaan pencabutan dilakukan pada sertifikat akhir dan hanya sertifikat akhir.
CERT_CHAIN_REVOCATION_CHECK_CHAIN
0x20000000		 Pemeriksaan pencabutan dilakukan pada semua sertifikat di setiap rantai.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x40000000		 Pemeriksaan pencabutan dilakukan pada semua sertifikat di semua rantai kecuali sertifikat akar.

[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 nonzero (TRUE).

Jika fungsi gagal, fungsi akan mengembalikan nol (FALSE). Untuk informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

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 pStrongSignPara anggota struktur CERT_CHAIN_PARA yang ditunjukkan 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 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 sertifikat akhir 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 dalam dwStrongSignFlags anggota 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 dalam bidang dwErrorStatus dari struktur CERT_TRUST_STATUS. Selain itu, dwRevocationResult anggota struktur CERT_REVOCATION_INFO diatur ke NTE_BAD_ALGID.

Rekomendasi berikut akan berlaku untuk aplikasi Windows apa pun yang memanggil API ini untuk memverifikasi sertifikat autentikasi server TLS:

  • Hanya aktifkan pemeriksaan pencabutan untuk sertifikat akhir.
    • Atur bendera CERT_CHAIN_REVOCATION_CHECK_END_CERT.
    • Sebagian besar sertifikat CA memiliki CRL dengan validitas waktu 1 hingga 6 bulan.
      • Karena CRL yang diunduh di-cache, validitas ini terlalu panjang untuk memiliki banyak nilai.
    • Jika ada penyusupan CA, maka sertifikat juga akan ditambahkan ke CTL Yang Tidak Diizinkan Windows
    • Praktik yang direkomendasikan untuk server TLS adalah mendukung stapling OCSP untuk sertifikat akhir.
      • Dalam hal ini, tidak ada pengambilan jaringan yang diperlukan kecuali respons OCSP yang di-stapling telah kedaluwarsa.
  • Aktifkan pengambilan jaringan untuk CRL, OCSP, penerbit AIA, dan kabin CTL platform Windows dan akar Pihak Ketiga.
    • Ketika CERT_CHAIN_REVOCATION_CHECK_END_CERT di atas diatur, ini adalah default.
    • Jangan atur salah satu bendera berikut untuk mencegah pengambilan jaringan. Lihat tabel dwFlags di atas untuk informasi selengkapnya tentang bendera ini:
      • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
      • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
      • CERT_CHAIN_DISABLE_AIA
  • Aktifkan batas waktu akumulatif untuk pengambilan jaringan CRL dan OCSP.
    • Atur bendera CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT yang diteruskan ke CertGetCertificateChain.
    • Menyediakan batas atas pada total waktu yang diizinkan untuk pengambilan jaringan CRL dan OCSP.
  • Kurangi waktu maksimum yang diizinkan untuk setiap pengambilan jaringan dari 15 menjadi 10 detik.
    • Atur bidang dwUrlRetrievalTimeout di CERT_CHAIN_PARA diteruskan ke CertGetCertificateChain menjadi 10 * 1000 milidetik.
    • Ini juga mengurangi batas waktu akumulatif dari 20 menjadi 10 detik.
      • Hanya respons OCSP yang harus diunduh untuk sertifikat akhir. 5 detik harus cukup untuk unduhan tersebut.
  • Abaikan kesalahan pencabutan offline.
    • Atur CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS dalam CERT_CHAIN_POLICY_PARA yang diteruskan ke CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL).
    • Pengambilan jaringan OCSP dan CRL adalah upaya terbaik. Sebagian besar pengambilan jaringan harus berhasil dalam beberapa detik, tetapi tidak dijamin 100%.
  • Informasi validasi sertifikat akhir cache.
    • Atur CERT_CHAIN_CACHE_END_CERT.
      • Memungkinkan penembolokan informasi LRU pada sertifikat akhir selain sertifikat perantara.
    • Adalah umum untuk membuat beberapa koneksi TLS ke server yang sama.

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Membuat Rantai Sertifikat.

Persyaratan

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

Lihat juga

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

Fungsi Verifikasi Rantai Sertifikat