Fungsi CertFindChainInStore (wincrypt.h)

Artikel
07/16/2024

Fungsi CertFindChainStore 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 tempat rantai dibangun dipilih sesuai dengan kriteria yang ditetapkan oleh dwFindFlags, dwFindType, dan parameter pvFindPara. Fungsi ini dapat digunakan dalam perulangan untuk menemukan semua sertifikat di penyimpanan sertifikat yang cocok dengan kriteria temuan yang ditentukan dan untuk membangun konteks rantai sertifikat untuk setiap sertifikat yang ditemukan.

Sintaksis

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 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. Jenis pengodean pesan pengidentifikasi, yang terkandung dalam WORD tinggi dari nilai ini, diabaikan oleh fungsi ini.

Parameter ini dapat berupa jenis pengodean sertifikat yang saat ini ditentukan berikut.

Nilai	Arti
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	Arti
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Membandingkan kunci publik dalam sertifikat dengan kunci publikpenyedia layanan kriptografi . Perbandingan ini adalah pemeriksaan terakhir yang dibuat pada rantai ketika dibangun. Karena hCryptProv anggota penerbit 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.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	Secara default, hanya rantai sederhana pertama yang diperiksa untuk kecocokan nama pengeluar sertifikat. Dengan set bendera ini, default 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 yang di-cache (Root, My, Ca, Trust) untuk menemukan sertifikat pengeluar sertifikat. Jika bendera ini tidak diatur, fungsi mencari penyimpanan sistem yang di-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 dapat berupa nilai berikut yang saat ini ditentukan.

CERT_CHAIN_FIND_BY_ISSUER

Menemukan sertifikat berdasarkan nama penerbit. 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 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) dalam rantai, bukan hanya otoritas sertifikasi dalam sertifikat akar.

Fungsi ini tidak melakukan pemeriksaan pencabutan.

Jika pPrevChainContext tidak 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 itu sendiri melalui panggilan ke fungsi CertVerifyRevocation dan menemukan rantai tidak sesuai, 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 yang berbeda atau NULL, jika tidak ada rantai tersebut yang dapat ditemukan.

[in] pvFindPara

Penunjuk yang berisi kriteria pencarian tambahan. Jenis dan format data yang dituju 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 tidak NULL, fungsi ini akan membebaskan struktur ini.

Mengembalikan nilai

Jika konteks rantai pertama atau berikutnya tidak dibuat, 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.

Komentar

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 tidak NULL, struktur selalu dibebaskan oleh fungsi ini dengan menggunakan fungsi CertFreeCertificateChain, bahkan jika terjadi kesalahan.

Persyaratan

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