Fungsi CertFindCertificateInStore (wincrypt.h)
Fungsi CertFindCertificateInStore
PCCERT_CONTEXT CertFindCertificateInStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwCertEncodingType,
[in] DWORD dwFindFlags,
[in] DWORD dwFindType,
[in] const void *pvFindPara,
[in] PCCERT_CONTEXT pPrevCertContext
);
[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-ATAU 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
[in] dwFindType
Menentukan jenis pencarian yang sedang dilakukan. Jenis pencarian menentukan jenis data, konten, dan penggunaan pvFindPara. Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Arti |
|---|---|
|
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.
|
|
Jenis data pvFindPara: struktur CERT_ID.
Temukan sertifikat yang diidentifikasi oleh CERT_IDyang ditentukan . |
|
Jenis data pvFindPara : struktur CTL_USAGE.
Mencari sertifikat yang memiliki ekstensi szOID_ENHANCED_KEY_USAGE atau CERT_CTL_PROP_ID yang cocok dengan pszUsageIdentifier anggota struktur CTL_USAGE. |
|
Jenis data pvFindPara: struktur CERT_ENHKEY_USAGE.
Mencari sertifikat di penyimpanan yang memiliki ekstensi penggunaan kunci yang ditingkatkan 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. Pengaturan 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 ke kriteria pencarian, lihat Keterangan. |
|
Jenis data pvFindPara : struktur CERT_CONTEXT.
Mencari sertifikat yang sama persis dengan konteks sertifikat yang ditentukan. |
|
Jenis data pvFindPara: struktur CRYPT_HASH_BLOB.
Mencari sertifikat dengan hash SHA1 yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB. |
|
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.
|
|
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 yang mencari kecocokan dengan atribut pengeluar sertifikat. Jika pszObjId anggota CERT_RDN_ATTRNULL, pengidentifikasi objek atribut diabaikan. Jika dwValueType anggota CERT_RDN_ATTR CERT_RDN_ANY_TYPE, jenis nilai diabaikan. Jika pbData anggota CERT_RDN_VALUE_BLOBNULL, nilai apa pun cocok. Saat ini hanya kecocokan yang tepat dan peka huruf besar/kecil yang didukung. Untuk informasi tentang opsi Unicode, lihat Komentar. Ketika nilai-nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dwCertEncodingType. |
|
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. |
|
Jenis data pvFindPara : struktur CERT_CONTEXT.
Mencari sertifikat dengan subjek yang cocok dengan penerbit di CERT_CONTEXT. Alih-alih menggunakan |
|
Jenis data pvFindPara: Untai (karakter) Unicode yang dihentikan null.
Mencari sertifikat yang berisi string nama pengeluar sertifikat yang ditentukan. Anggota penerbit sertifikat dikonversi ke string nama dengan jenis yang sesuai menggunakan bentuk CertNameToStr yang sesuai diformat sebagai CERT_SIMPLE_NAME_STR. Kemudian substring-within-a-string yang tidak peka huruf besar/kecil akan dilakukan. Ketika nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dwCertEncodingType. Jika kecocokan substring gagal dan subjek berisi RDN email dengan string yang dikodekan Punycode, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG digunakan untuk mengonversi subjek ke string Unicode dan kecocokan substring dilakukan lagi. |
|
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. |
|
Jenis datapvFindPara Mencari sertifikat yang memiliki properti CERT_KEY_SPEC_PROP_ID yang cocok dengan spesifikasi kunci di pvFindPara. |
|
Jenis data pvFindPara: struktur CRYPT_HASH_BLOB.
Mencari sertifikat dengan hash MD5 yang cocok dengan hash di CRYPT_HASH_BLOB. |
|
Jenis data pvFindPara : variabel DWORD yang berisi pengidentifikasi properti.
Mencari sertifikat dengan properti yang cocok dengan pengidentifikasi properti yang ditentukan oleh nilai DWORD |
|
Jenis data pvFindPara : struktur CERT_PUBLIC_KEY_INFO.
Mencari sertifikat dengan kunci umum yang cocok dengan kunci publik dalam struktur CERT_PUBLIC_KEY_INFO. |
|
Jenis data pvFindPara: struktur CRYPT_HASH_BLOB.
Mencari sertifikat dengan hash SHA1 yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB. |
|
Jenis data pvFindPara: struktur CRYPT_HASH_BLOB.
Mencari sertifikat dengan hash SHA1 + SHA256 yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB. |
|
Jenis data pvFindPara: struktur CRYPT_HASH_BLOB.
Mencari sertifikat dengan hash SHA256 yang cocok dengan hash dalam struktur CRYPT_HASH_BLOB. |
|
Jenis data pvFindPara: struktur CRYPT_HASH_BLOB.
Mencari sertifikat dengan hash tanda tangan yang cocok dengan hash tanda tangan dalam struktur CRYPT_HASH_BLOB. |
|
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 yang mencari kecocokan dengan atribut subjek sertifikat. Jika pszObjId anggota CERT_RDN_ATTRNULL, pengidentifikasi objek atribut diabaikan. Jika dwValueType anggota CERT_RDN_ATTR CERT_RDN_ANY_TYPE, jenis nilai diabaikan. Jika pbData anggota CERT_RDN_VALUE_BLOBNULL, nilai apa pun cocok. Saat ini hanya kecocokan yang tepat dan peka huruf besar/kecil yang didukung. Untuk informasi tentang opsi Unicode, lihat Komentar. Ketika nilai-nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dwCertEncodingType. |
|
Jenis data pvFindPara : struktur CERT_INFO.
Mencari sertifikat dengan penerbit dan nomor seri yang cocok dengan penerbit dan nomor seri dalam struktur CERT_INFO. |
|
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. |
|
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 diformat sebagai CERT_SIMPLE_NAME_STR. Kemudian substring-within-a-string yang tidak peka huruf besar/kecil akan dilakukan. Ketika nilai ini diatur, pencarian dibatasi untuk sertifikat yang jenis pengodeannya cocok dwCertEncodingType. |
|
Jenis data pvFindPara: Tidak digunakan.
Temukan sertifikat yang memiliki ekstensi atau properti titik distribusi lintas sertifikat. |
|
Jenis data pvFindPara: struktur CRYPT_HASH_BLOB.
Temukan sertifikat yang kunci publiknya di-hash MD5-nya cocok dengan hash yang ditentukan. |
[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
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 pengembalian NULL.
Untuk informasi kesalahan yang diperluas, panggil GetLastError. Beberapa kemungkinan kode kesalahan mengikuti.
| Mengembalikan kode | Deskripsi |
|---|---|
|
Tidak ditemukan sertifikat yang cocok dengan kriteria pencarian. Ini dapat terjadi jika penyimpanan kosong atau akhir daftar toko tercapai. |
|
Handel dalam parameter hCertStore |
Parameter
Nilai CERT_UNICODE_IS_RDN_ATTRS_FLAG
Nilai
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 saat diteruskan sebagai parameter
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 Kumpulan dan Penyimpanan Sertifikat Saudara.
#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);
| 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 |
CertAddCertificateContextToStore
CertDuplicateCertificateContext
Fungsi Sertifikat