Fungsi CertFindCertificateInStore (wincrypt.h)

Artikel
03/15/2023

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

Sintaks

PCCERT_CONTEXT CertFindCertificateInStore(
  [in] HCERTSTORE     hCertStore,
  [in] DWORD          dwCertEncodingType,
  [in] DWORD          dwFindFlags,
  [in] DWORD          dwFindType,
  [in] const void     *pvFindPara,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Parameter

[in] hCertStore

Handel penyimpanan sertifikat yang akan dicari.

[in] dwCertEncodingType

Menentukan jenis pengodean yang digunakan. Jenis pengodean sertifikat dan pesan harus ditentukan 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

[in] dwFindFlags

Digunakan dengan beberapa nilai dwFindType untuk mengubah kriteria pencarian. Untuk sebagian besar nilai dwFindType , dwFindFlags tidak digunakan dan harus diatur ke nol. Untuk informasi selengkapnya, lihat Keterangan.

[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
CERT_FIND_ANY	Jenis data pvFindPara: NULL, tidak digunakan. Tidak ada kriteria pencarian yang digunakan. Mengembalikan sertifikat berikutnya di penyimpanan. Catatan Urutan konteks sertifikat mungkin tidak dipertahankan dalam penyimpanan. Untuk mengakses sertifikat tertentu, Anda harus melakukan iterasi di seluruh sertifikat di penyimpanan.
CERT_FIND_CERT_ID	Jenis data pvFindPara: struktur CERT_ID . Temukan sertifikat yang diidentifikasi oleh CERT_ID yang ditentukan.
CERT_FIND_CTL_USAGE	Jenis data pvFindPara: struktur CTL_USAGE . Mencari sertifikat yang memiliki ekstensi szOID_ENHANCED_KEY_USAGE atau CERT_CTL_PROP_ID yang cocok dengan anggota pszUsageIdentifier dari struktur CTL_USAGE .
CERT_FIND_ENHKEY_USAGE	Jenis data pvFindPara: struktur CERT_ENHKEY_USAGE . Mencari sertifikat di penyimpanan yang memiliki ekstensi penggunaan kunci yang ditingkatkan atau properti penggunaan kunci yang ditingkatkan dan pengidentifikasi penggunaan yang cocok dengan anggota cUsageIdentifier dalam struktur CERT_ENHKEY_USAGE . Sertifikat memiliki ekstensi penggunaan kunci yang disempurnakan jika memiliki struktur CERT_EXTENSION dengan anggota pszObjId diatur ke szOID_ENHANCED_KEY_USAGE. Sertifikat memiliki properti penggunaan kunci yang ditingkatkan jika pengidentifikasi CERT_ENHKEY_USAGE_PROP_ID diatur. Jika CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG diatur dalam dwFindFlags, sertifikat tanpa ekstensi penggunaan kunci atau properti juga cocok. Mengatur bendera ini lebih diutamakan daripada melewati NULL di pvFindPara. Jika CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG diatur, kecocokan hanya dilakukan pada ekstensi penggunaan kunci. Untuk informasi tentang modifikasi bendera pada kriteria pencarian, lihat Keterangan.
CERT_FIND_EXISTING	Jenis data pvFindPara: struktur CERT_CONTEXT . Mencari sertifikat yang sama persis dengan konteks sertifikat yang ditentukan.
CERT_FIND_HASH	Jenis data pvFindPara: struktur CRYPT_HASH_BLOB . Mencari sertifikat dengan hash SHA1 yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB .
CERT_FIND_HAS_PRIVATE_KEY	Jenis data pvFindPara: NULL, tidak digunakan. Mencari sertifikat yang memiliki kunci privat. Kunci dapat bersifat ephemeral atau disimpan pada disk. Kuncinya dapat berupa kunci API Kriptografi (CAPI) warisan atau kunci CNG. Catatan Urutan konteks sertifikat mungkin tidak dipertahankan dalam penyimpanan. Oleh karena itu, untuk mengakses sertifikat tertentu, Anda harus melakukan iterasi di semua sertifikat. Windows 8 dan Windows Server 2012: Dukungan untuk bendera ini dimulai.
CERT_FIND_ISSUER_ATTR	Jenis data pvFindPara: struktur CERT_RDN . Mencari sertifikat dengan atribut pengeluar sertifikat tertentu yang cocok dengan atribut dalam struktur CERT_RDN . Jika nilai-nilai ini diatur, fungsi membandingkan atribut penerbit dalam sertifikat dengan elemen array CERT_RDN_ATTR dalam struktur CERT_RDN ini. Perbandingan iterasi melalui atribut CERT_RDN_ATTR mencari kecocokan dengan atribut penerbit sertifikat. Jika anggota pszObjIddari CERT_RDN_ATTR adalah NULL, pengidentifikasi objek atribut diabaikan. Jika anggota dwValueTypedari CERT_RDN_ATTR CERT_RDN_ANY_TYPE, jenis nilai diabaikan. Jika anggota pbDatadari CERT_RDN_VALUE_BLOB adalah NULL, nilai apa pun cocok. Saat ini hanya kecocokan yang tepat dan peka huruf besar/kecil yang didukung. Untuk informasi tentang opsi Unicode, lihat Keterangan. Ketika nilai-nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dengan dwCertEncodingType.
CERT_FIND_ISSUER_NAME	Jenis data pvFindPara: struktur CERT_NAME_BLOB . Cari sertifikat dengan kecocokan yang tepat dari seluruh nama pengeluar sertifikat dengan nama di CERT_NAME_BLOB Pencarian dibatasi untuk sertifikat yang cocok dengan dwCertEncodingType.
CERT_FIND_ISSUER_OF	Jenis data pvFindPara: struktur CERT_CONTEXT . Mencari sertifikat dengan subjek yang cocok dengan pengeluar sertifikat di CERT_CONTEXT. Alih-alih menggunakan CertFindCertificateInStore dengan nilai ini, gunakan fungsi CertGetCertificateChain .
CERT_FIND_ISSUER_STR	Jenis data pvFindPara: Untai (karakter) Unicode yang dihentikan null. Mencari sertifikat yang berisi string nama pengeluar sertifikat yang ditentukan. Anggota pengeluar sertifikat dikonversi ke string nama dengan jenis yang sesuai menggunakan bentuk CertNameToStr yang sesuai yang diformat sebagai CERT_SIMPLE_NAME_STR. Kemudian pencocokan substring-within-a-string yang tidak sensitif huruf besar/kecil dilakukan. Ketika nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dengan dwCertEncodingType. Jika pencocokan substring gagal dan subjek berisi email RDN dengan string yang dikodekan Punycode, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG digunakan untuk mengonversi subjek ke string Unicode dan pencocokan substring dilakukan lagi.
CERT_FIND_KEY_IDENTIFIER	Jenis data pvFindPara: struktur CRYPT_HASH_BLOB . Mencari sertifikat dengan properti CERT_KEY_IDENTIFIER_PROP_ID yang cocok dengan pengidentifikasi kunci di CRYPT_HASH_BLOB.
CERT_FIND_KEY_SPEC	Jenis data pvFindPara: Variabel DWORD yang berisi spesifikasi utama. Mencari sertifikat yang memiliki properti CERT_KEY_SPEC_PROP_ID yang cocok dengan spesifikasi kunci di pvFindPara.
CERT_FIND_MD5_HASH	Jenis data pvFindPara: struktur CRYPT_HASH_BLOB . Mencari sertifikat dengan hash MD5 yang cocok dengan hash di CRYPT_HASH_BLOB.
CERT_FIND_PROPERTY	Jenis data pvFindPara: Variabel DWORD yang berisi pengidentifikasi properti. Mencari sertifikat dengan properti yang cocok dengan pengidentifikasi properti yang ditentukan oleh nilai DWORD di pvFindPara.
CERT_FIND_PUBLIC_KEY	Jenis data pvFindPara: struktur CERT_PUBLIC_KEY_INFO . Mencari sertifikat dengan kunci umum yang cocok dengan kunci umum dalam struktur CERT_PUBLIC_KEY_INFO .
CERT_FIND_SHA1_HASH	Jenis data pvFindPara: struktur CRYPT_HASH_BLOB . Mencari sertifikat dengan hash SHA1 yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB .
CERT_FIND_SIGNATURE_HASH	Jenis data pvFindPara: struktur CRYPT_HASH_BLOB . Mencari sertifikat dengan hash tanda tangan yang cocok dengan hash tanda tangan dalam struktur CRYPT_HASH_BLOB .
CERT_FIND_SUBJECT_ATTR	Jenis data pvFindPara: struktur CERT_RDN . Mencari sertifikat dengan atribut subjek tertentu yang cocok dengan atribut dalam struktur CERT_RDN . Jika nilai RDN diatur, fungsi membandingkan atribut subjek dalam sertifikat dengan elemen array CERT_RDN_ATTR dalam struktur CERT_RDN ini. Perbandingan iterasi melalui atribut CERT_RDN_ATTR mencari kecocokan dengan atribut subjek sertifikat. Jika anggota pszObjIddari CERT_RDN_ATTR adalah NULL, pengidentifikasi objek atribut diabaikan. Jika anggota dwValueTypedari CERT_RDN_ATTR CERT_RDN_ANY_TYPE, jenis nilai diabaikan. Jika anggota pbDatadari CERT_RDN_VALUE_BLOB adalah NULL, nilai apa pun cocok. Saat ini hanya kecocokan yang tepat dan peka huruf besar/kecil yang didukung. Untuk informasi tentang opsi Unicode, lihat Keterangan. Ketika nilai-nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dengan dwCertEncodingType.
CERT_FIND_SUBJECT_CERT	Jenis data pvFindPara: struktur CERT_INFO . Mencari sertifikat dengan pengeluar sertifikat dan nomor seri yang cocok dengan penerbit dan nomor seri dalam struktur CERT_INFO .
CERT_FIND_SUBJECT_NAME	Jenis data pvFindPara: struktur CERT_NAME_BLOB . Mencari sertifikat dengan kecocokan yang tepat dari seluruh nama subjek dengan nama dalam struktur CERT_NAME_BLOB . Pencarian dibatasi untuk sertifikat yang cocok dengan nilai dwCertEncodingType.
CERT_FIND_SUBJECT_STR	Jenis data pvFindPara: Untai (karakter) Unicode yang dihentikan null. Mencari sertifikat yang berisi string nama subjek yang ditentukan. Anggota subjek sertifikat dikonversi ke string nama dengan jenis yang sesuai menggunakan bentuk CertNameToStr yang sesuai yang diformat sebagai CERT_SIMPLE_NAME_STR. Kemudian pencocokan substring-within-a-string yang tidak sensitif huruf besar/kecil dilakukan. Ketika nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dengan dwCertEncodingType.
CERT_FIND_CROSS_CERT_DIST_POINTS	Jenis data pvFindPara: Tidak digunakan. Temukan sertifikat yang memiliki ekstensi atau properti titik distribusi lintas sertifikat.
CERT_FIND_PUBKEY_MD5_HASH	Jenis data pvFindPara: struktur CRYPT_HASH_BLOB . Temukan sertifikat yang kunci publiknya di-hash MD5 cocok dengan hash yang ditentukan.

Catatan Ada bentuk alternatif dari nilai dwFindType yang meneruskan string di pvFindPara. Satu formulir menggunakan string Unicode, dan yang lainnya string ASCII . Nilai yang berakhiran "_W" atau tanpa akhiran menggunakan Unicode. Nilai yang diakhir dengan "_A" menggunakan string ASCII.

[in] pvFindPara

Menunjuk ke item data atau struktur yang digunakan dengan dwFindType.

[in] pPrevCertContext

Penunjuk ke struktur CERT_CONTEXT terakhir yang dikembalikan oleh fungsi ini. Parameter ini harus NULL pada panggilan pertama fungsi. Untuk menemukan sertifikat berturut-turut yang memenuhi kriteria pencarian, atur pPrevCertContext ke penunjuk yang dikembalikan oleh panggilan sebelumnya ke fungsi. Fungsi ini membebaskan CERT_CONTEXT yang dirujuk oleh nilai non-NULL dari parameter ini.

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan penunjuk ke struktur CERT_CONTEXT baca-saja.

Jika fungsi gagal dan sertifikat yang cocok dengan kriteria pencarian tidak ditemukan, nilai yang dikembalikan adalah NULL.

CERT_CONTEXTnon-NULL yang dikembalikan CertFindCertificateInStore harus dibebaskan oleh CertFreeCertificateContext atau dengan diteruskan sebagai parameter pPrevCertContext pada panggilan berikutnya ke CertFindCertificateInStore.

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

Menampilkan kode	Deskripsi
CRYPT_E_NOT_FOUND	Tidak ditemukan sertifikat yang cocok dengan kriteria pencarian. Ini dapat terjadi jika penyimpanan kosong atau akhir daftar toko tercapai.
E_INVALIDARG	Handel dalam parameter hCertStore tidak sama dengan yang dalam konteks sertifikat yang diarahkan oleh parameter pPrevCertContext , atau nilai yang tidak valid ditentukan dalam parameter dwFindType .

Keterangan

Parameter dwFindFlags digunakan untuk memodifikasi kriteria beberapa jenis pencarian.

Nilai CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags hanya digunakan dengan nilai CERT_FIND_SUBJECT_ATTR dan CERT_FIND_ISSUER_ATTR untuk dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG harus diatur jika struktur CERT_RDN_ATTR yang diacu oleh pvFindPara diinisialisasi dengan string Unicode. Sebelum perbandingan dibuat, string yang akan dicocokkan dikonversi dengan menggunakan X509_UNICODE_NAME untuk menyediakan perbandingan Unicode.

Nilai dwFindFlags berikut ini hanya digunakan dengan nilai CERT_FIND_ENKEY_USAGE untuk dwFindType:

CertDuplicateCertificateContext dapat dipanggil untuk membuat duplikat konteks yang dikembalikan. Konteks yang dikembalikan dapat ditambahkan ke penyimpanan sertifikat yang berbeda dengan menggunakan CertAddCertificateContextToStore, atau tautan ke konteks sertifikat tersebut dapat ditambahkan ke penyimpanan yang bukan penyimpanan koleksi dengan menggunakan CertAddCertificateLinkToStore.

Pointer yang dikembalikan dibebaskan ketika diteruskan sebagai parameter pPrevCertContext pada panggilan berikutnya ke fungsi. Jika tidak, pointer harus dibebaskan secara eksplisit dengan memanggil CertFreeCertificateContext. pPrevCertContext yang bukan NULL selalu dibebaskan oleh CertFindCertificateInStore menggunakan panggilan ke CertFreeCertificateContext, bahkan jika ada kesalahan dalam fungsi.

Contoh

Contoh berikut menunjukkan menemukan konteks sertifikat di penyimpanan sertifikat yang memenuhi kriteria pencarian. Untuk contoh lengkap yang menyertakan konteks untuk contoh ini, lihat Contoh Program C: Operasi Penyimpanan Sertifikat.

Untuk contoh lain yang menggunakan fungsi ini, lihat Contoh Program C: Operasi Penyimpanan Sertifikat Koleksi dan Saudara Kandung.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")

#define MY_ENCODING_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)

void main()
{
//-------------------------------------------------------------------
// Declare and initialize variables.
HCERTSTORE  hSystemStore;              // The system store handle.
PCCERT_CONTEXT  pDesiredCert = NULL;   // Set to NULL for the first 
                                       // call to
                                       // CertFindCertificateInStore.
LPCSTR lpszCertSubject = (LPCSTR) "Cert_subject_1";


//-------------------------------------------------------------------
// Open the certificate store to be searched.

if(hSystemStore = CertOpenStore(
     CERT_STORE_PROV_SYSTEM, 
     0,                      // Encoding type not needed 
                             // with this PROV.
     NULL,                   // Accept the default HCRYPTPROV. 
     CERT_SYSTEM_STORE_CURRENT_USER,
                             // Set the system store location in 
                             // the registry.
     L"MY"))                 // Could have used other predefined 
                             // system stores
                             // including Trust, CA, or Root.
{
   printf("Opened the MY system store. \n");
}
else
{
   printf( "Could not open the MY system store.\n");
   exit(1);
}
//-------------------------------------------------------------------
// Get a certificate that has lpszCertSubject as its 
// subject. 

if(pDesiredCert=CertFindCertificateInStore(
      hSystemStore,
      MY_ENCODING_TYPE,           // Use X509_ASN_ENCODING.
      0,                          // No dwFlags needed. 
      CERT_FIND_SUBJECT_STR,      // Find a certificate with a
                                  // subject that matches the string
                                  // in the next parameter.
      lpszCertSubject ,           // The Unicode string to be found
                                  // in a certificate's subject.
      NULL))                      // NULL for the first call to the
                                  // function. In all subsequent
                                  // calls, it is the last pointer
                                  // returned by the function.
{
  printf("The desired certificate was found. \n");
}
else
{
   printf("Could not find the desired certificate.\n");
}
//-------------------------------------------------------------------
// Clean up. 

if(pDesiredCert)
    CertFreeCertificateContext(pDesiredCert);
if(hSystemStore)
    CertCloseStore(
        hSystemStore, 
        CERT_CLOSE_STORE_CHECK_FLAG);

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