Fungsi CertFindCTLInStore (wincrypt.h)

Artikel
03/15/2023

Fungsi CertFindCTLInStore menemukan konteks daftar kepercayaan sertifikat (CTL) pertama atau berikutnya yang cocok dengan kriteria pencarian yang ditetapkan oleh dwFindType dan pvFindPara terkait. Fungsi ini dapat digunakan dalam perulangan untuk menemukan semua konteks CTL di penyimpanan sertifikat yang cocok dengan kriteria temukan yang ditentukan.

Sintaks

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Parameter

[in] hCertStore

Menangani penyimpanan sertifikat yang akan dicari.

[in] dwMsgAndCertEncodingType

Menentukan jenis pengodean yang digunakan pada CTL. Selalu dapat diterima untuk menentukan jenis pengodean sertifikat dan pesan dengan menggabungkannya dengan operasi bitwise-OR seperti yang ditunjukkan dalam contoh berikut:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING Jenis pengodean yang ditentukan saat ini adalah:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

Parameter ini hanya digunakan ketika parameter dwFindType diatur ke CTL_FIND_USAGE.

[in] dwFindFlags

Dapat diatur ketika dwFindType diatur ke CTL_FIND_USAGE. Untuk detailnya, lihat komentar di bawah CTL_FIND_USAGE, berikut ini.

[in] dwFindType

Menentukan tipe pencarian yang sedang dilakukan. Jenis pencarian menentukan jenis data, konten, dan penggunaan pvFindPara. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
CTL_FIND_ANY	Jenis data pvFindPara: NULL. CTL apa pun cocok.
CTL_FIND_SHA1_HASH	Jenis data pvFindPara: CRYPT_HASH_BLOB. CTL dengan hash yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB ditemukan.
CTL_FIND_MD5_HASH	Jenis data pvFindPara: CRYPT_HASH_BLOB. CTL dengan hash yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB ditemukan.
CTL_FIND_USAGE	Jenis data pvFindPara: CTL_FIND_USAGE_PARA. Setiap CTL ditemukan yang memiliki pengidentifikasi penggunaan, pengidentifikasi daftar, atau penanda tangan yang cocok dengan pengidentifikasi penggunaan, pengidentifikasi daftar, atau penanda tangan dalam struktur CTL_FIND_USAGE_PARA . Jika anggota cUsageIdentifier berukuran SubjectUsage , CTL apa pun cocok. Jika anggota cbData anggota ListIdentifier adalah nol, pengidentifikasi daftar apa pun cocok. Jika anggota cbDataListIdentifier CTL_FIND_NO_LIST_ID_CBDATA, hanya CTL tanpa pengidentifikasi daftar yang cocok. Jika anggota pSigner dalam struktur CTL_FIND_USAGE_PARAadalah NULL, penanda tangan CTL apa pun adalah kecocokan, dan hanya anggota Penerbit dan SerialNumber dalam struktur CERT_INFOpSigner yang digunakan. Jika pSigner CTL_FIND_NO_SIGNER_PTR, hanya CTL tanpa penanda tangan yang cocok.
CTL_FIND_SAME_USAGE_FLAG	Jenis data pvFindPara: CTL_FIND_USAGE_PARA. Hanya CCL dengan pengidentifikasi penggunaan yang sama persis yang cocok. CTL yang memiliki pengidentifikasi penggunaan tambahan tidak cocok. Misalnya, jika hanya "1.2.3" yang ditentukan dalam struktur CTL_FIND_USAGE_PARA , maka untuk kecocokan, CTL hanya boleh berisi "1.2.3" dan tidak ada pengidentifikasi penggunaan tambahan.
CTL_FIND_EXISTING	Jenis data pvFindPara: PCCTL_CONTEXT. Mencari CRL berikutnya yang sama persis dengan CTL_CONTEXT.
CTL_FIND_SUBJECT	Jenis data pvFindPara: CTL_FIND_SUBJECT_PARA. CTL yang memiliki subjek yang ditentukan ditemukan. CertFindSubjectInCTL dapat dipanggil untuk mendapatkan penunjuk ke entri subjek di CTL. Anggota pUsagePara di CTL_FIND_SUBJECT_PARA secara opsional dapat diatur untuk mengaktifkan pencocokan yang dijelaskan sebelumnya di bawah CTL_FIND_USAGE.

[in] pvFindPara

Penunjuk ke nilai pencarian yang terkait dengan parameter dwFindType .

[in] pPrevCtlContext

Penunjuk ke CTL_CONTEXT terakhir yang dikembalikan oleh fungsi ini. Harus NULL untuk mendapatkan CTL pertama di toko. CCL berturut-turut diambil dengan mengatur pPrevCtlContext ke penunjuk ke CTL_CONTEXT yang dikembalikan oleh panggilan fungsi sebelumnya. Sertifikat apa pun yang tidak memenuhi kriteria pencarian atau yang sebelumnya telah dihapus oleh CertDeleteCTLFromStore dilewati. Fungsi ini membebaskan CTL_CONTEXT yang dirujuk oleh nilai non-NULL dari parameter ini.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah penunjuk ke konteks CTL baca-saja.

Untuk informasi kesalahan yang diperluas, hubungi GetLastError. Beberapa kemungkinan kode kesalahan mengikuti.

Menampilkan kode	Deskripsi
CRYPT_E_NOT_FOUND	Baik tidak ada CTL yang ditemukan di penyimpanan, tidak ada CTL yang ditemukan yang cocok dengan kriteria pencarian, atau fungsi mencapai akhir daftar penyimpanan.
E_INVALIDARG	Handel dalam parameter hCertStore tidak sama dengan yang dalam konteks CTL yang diarahkan oleh parameter pPrevCtlContext , atau nilai yang tidak valid ditentukan dalam parameter dwFindType .

Keterangan

Pointer yang dikembalikan dibebaskan saat diteruskan sebagai pPrevCtlContext pada panggilan berikutnya ke fungsi. Jika tidak, pointer harus dibebaskan dengan memanggil CertFreeCTLContext. pPrevCtlContextnon-NULL yang diteruskan ke fungsi selalu dibebaskan dengan panggilan ke CertFreeCTLContext, bahkan jika fungsi menghasilkan kesalahan.

CertDuplicateCTLContext dapat dipanggil untuk membuat duplikat konteks yang dikembalikan. Konteks CTL yang dikembalikan dapat ditambahkan ke penyimpanan sertifikat yang berbeda menggunakan CertAddCTLContextToStore, atau tautan ke konteks CTL tersebut dapat ditambahkan ke penyimpanan nonkoleksi menggunakan CertAddCTLLinkToStore. Jika CTL yang cocok dengan kriteria pencarian tidak ditemukan, NULL dikembalikan.

Persyaratan

Persyaratan	Nilai
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