Fungsi CertFindChainInStore (wincrypt.h)

Artikel
03/15/2023

Fungsi CertFindChainInStore menemukan sertifikat pertama atau berikutnya di penyimpanan yang memenuhi kriteria yang ditentukan. Kemudian membangun dan memverifikasi konteks rantai sertifikat untuk sertifikat tersebut. Sertifikat yang ditemukan dan yang rantainya dibangun dipilih sesuai dengan kriteria yang ditetapkan oleh parameter dwFindFlags, dwFindType, dan pvFindPara . Fungsi ini dapat digunakan dalam perulangan untuk menemukan semua sertifikat di penyimpanan sertifikat yang cocok dengan kriteria temukan yang ditentukan dan untuk membangun konteks rantai sertifikat untuk setiap sertifikat yang ditemukan.

Sintaks

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

Parameter

[in] hCertStore

Handel toko yang akan dicari untuk sertifikat tempat rantai dibangun. Handel ini diteruskan sebagai penyimpanan tambahan ke fungsi CertGetCertificateChain saat rantai dibangun.

[in] dwCertEncodingType

Jenis pengodean sertifikat yang digunakan untuk mengodekan penyimpanan. Pengidentifikasi jenis pengodean pesan, yang terkandung dalam WORD tinggi dari nilai ini, diabaikan oleh fungsi ini.

Parameter ini bisa menjadi jenis pengodean sertifikat yang saat ini ditentukan berikut.

Nilai	Makna
X509_ASN_ENCODING 1 (0x1)	Menentukan pengodean sertifikat X.509.

[in] dwFindFlags

Berisi opsi tambahan untuk pencarian. Nilai yang mungkin untuk parameter ini bergantung pada nilai parameter dwFindType .

Parameter ini dapat berisi nol atau kombinasi dari satu atau beberapa nilai berikut saat dwFindType berisi CERT_CHAIN_FIND_BY_ISSUER.

Nilai	Makna
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Membandingkan kunci umum dalam sertifikat dengan kunci umum penyedia layanan kriptografi. Perbandingan ini adalah pemeriksaan terakhir yang dilakukan pada rantai ketika dibangun. Karena anggota hCryptProv dari pengeluar sertifikat berisi kunci privat, mungkin perlu diperiksa beberapa kali selama proses ini; untuk memfasilitasi pemeriksaan ini, anggota dwAcquirePrivateKeyFlags dapat diatur dalam struktur CERT_CHAIN_FIND_BY_ISSUER_PARA untuk mengaktifkan penembolokan hCryptProv tersebut.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	Secara default, hanya rantai sederhana pertama yang diperiksa untuk kecocokan nama penerbit. Dengan set bendera ini, defaultnya ditimpa dan rantai sederhana berikutnya juga diperiksa untuk kecocokan nama pengeluar sertifikat.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Meningkatkan performa fungsi ini dengan menyebabkannya hanya mencari penyimpanan sistem cache (Root, My, Ca, Trust) untuk menemukan sertifikat penerbit. Jika bendera ini tidak diatur, fungsi mencari penyimpanan sistem cache dan penyimpanan yang diwakili oleh parameter hCertStore .
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Hanya cache URL yang dicari. Internet tidak dicari.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Hanya membuka penyimpanan sertifikat Komputer Lokal. Penyimpanan sertifikat pengguna saat ini tidak dibuka.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Tidak ada pemeriksaan yang dilakukan untuk menentukan apakah sertifikat memiliki kunci privat terkait.

[in] dwFindType

Menentukan kriteria apa yang akan digunakan untuk menemukan sertifikat di penyimpanan.

Parameter ini bisa menjadi nilai berikut yang saat ini ditentukan.

CERT_CHAIN_FIND_BY_ISSUER

Menemukan sertifikat berdasarkan nama pengeluar sertifikat. Parameter pvFindPara adalah penunjuk ke struktur CERT_CHAIN_FIND_BY_ISSUER_PARA yang berisi anggota yang memodifikasi pencarian.

Rantai sertifikat dibangun untuk sertifikat dengan kunci privat yang tersedia. Secara default, hanya penerbit dalam rantai sederhana pertama yang dibandingkan dalam kecocokan nama penerbit. Jika bendera ini diatur, semua rantai diperiksa untuk sertifikat pengeluar sertifikat yang cocok dengan salah satu set nama pengeluar sertifikat.

Fungsi ini akan membandingkan nama BLOB yang diteruskan dalam struktur pvFindPara dengan otoritas sertifikasi (CA) apa pun dalam rantai, bukan hanya otoritas sertifikasi dalam sertifikat akar.

Fungsi ini tidak melakukan pemeriksaan pencabutan apa pun.

Jika pPrevChainContext bukan NULL, fungsi ini akan mengembalikan rantai untuk sertifikat yang berbeda setiap kali fungsi dipanggil. Jika hanya ada satu sertifikat yang cocok, tetapi ada dua otoritas sertifikat penerbit yang cocok, salah satunya dicabut, dimungkinkan bagi fungsi ini untuk mengembalikan rantai yang dicabut. Jika aplikasi kemudian memeriksa pencabutan dirinya sendiri melalui panggilan ke fungsi CertVerifyRevocation dan menemukan rantai tidak cocok, panggilan tambahan ke fungsi CertFindChainInStore tidak akan mengembalikan rantai yang menyertakan sertifikat yang sama dari otoritas sertifikasi yang valid. Sebaliknya akan mengembalikan rantai yang sama sekali berbeda dengan sertifikat atau NULL yang berbeda, jika tidak ada rantai tersebut yang dapat ditemukan.

[in] pvFindPara

Penunjuk yang berisi kriteria pencarian tambahan. Jenis dan format data yang ditujukan parameter ini bergantung pada nilai parameter dwFindType .

[in] pPrevChainContext

Penunjuk ke struktur CERT_CHAIN_CONTEXT yang dikembalikan dari panggilan sebelumnya ke fungsi ini. Pencarian dimulai dari sertifikat ini. Untuk panggilan pertama ke fungsi ini, parameter ini harus NULL. Dalam panggilan berikutnya, ini adalah penunjuk yang dikembalikan oleh panggilan sebelumnya ke fungsi. Jika parameter ini bukan NULL, fungsi ini akan membebaskan struktur ini.

Nilai kembali

Jika konteks rantai pertama atau berikutnya tidak dibangun, NULL dikembalikan. Jika tidak, penunjuk ke struktur CERT_CHAIN_CONTEXT baca-saja dikembalikan. Struktur CERT_CHAIN_CONTEXT dibebaskan ketika diteruskan sebagai parameter pPrevChainContext pada panggilan berikutnya ke fungsi ini. Jika tidak, struktur CERT_CHAIN_CONTEXT harus dibebaskan secara eksplisit dengan memanggil fungsi CertFreeCertificateChain .

Keterangan

Parameter pPrevChainContext harus NULL pada panggilan pertama untuk membangun konteks rantai. Untuk membangun konteks rantai berikutnya, pPrevChainContext diatur ke struktur CERT_CHAIN_CONTEXT yang dikembalikan oleh panggilan sebelumnya. Jika pPrevChainContext bukan NULL, struktur selalu dibebaskan oleh fungsi ini dengan menggunakan fungsi CertFreeCertificateChain , bahkan jika terjadi kesalahan.

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	wincrypt.h
Pustaka	Crypt32.lib
DLL	Crypt32.dll