Fungsi CertSelectCertificateChains (wincrypt.h)

  • Artikel

Fungsi CertSelectCertificateChains mengambil rantai sertifikat berdasarkan kriteria pilihan yang ditentukan.

Sintaks

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

Parameter

[in, optional] pSelectionContext

Penunjuk ke GUID skenario pemilihan sertifikat yang akan digunakan untuk panggilan ini.

[in] dwFlags

Bendera untuk mengontrol proses pemilihan sertifikat. Parameter ini dapat berupa kombinasi nol atau lebih dari bendera berikut:

Nilai Makna
CERT_SELECT_ALLOW_EXPIRED
 Pilih sertifikat kedaluwarsa yang memenuhi kriteria pilihan. Secara default sertifikat yang kedaluwarsa ditolak dari pilihan.
CERT_SELECT_TRUSTED_ROOT
 Pilih sertifikat tempat bit kesalahan dalam status kepercayaan rantai sertifikat tidak diatur ke CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN, atau CERT_TRUST_IS_NOT_TIME_VALID.

Selain itu, sertifikat yang memiliki salah satu kesalahan batasan tidak valid berikut ini tidak dipilih:

  • CERT_TRUST_INVALID_POLICY_CONSTRAINTS
  • CERT_TRUST_INVALID_BASIC_CONSTRAINTS
  • CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED
 Pilih sertifikat yang tidak diterbitkan sendiri dan ditandatangani sendiri.
CERT_SELECT_HAS_PRIVATE_KEY
 Pilih sertifikat yang memiliki nilai yang ditetapkan untuk properti CERT_KEY_PROV_INFO_PROP_ID sertifikat.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE
 Pilih sertifikat tempat nilai anggota dwKeySpec properti CERT_KEY_PROV_INFO_PROP_ID diatur ke AT_SIGNATURE.

Jika fungsi ini dipanggil sebagai bagian dari aplikasi yang diaktifkan CNG dan anggota dwKeySpec dari properti CERT_KEY_PROV_INFO_PROP_ID diatur ke -1, pilih sertifikat tempat nilai properti NCRYPT_KEY_USAGE_PROPERTY dari kunci privat terkait memiliki set NCRYPT_ALLOW_SIGNING_FLAG .
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE
 Pilih sertifikat tempat nilai anggota dwKeySpec properti CERT_KEY_PROV_INFO_PROP_ID diatur ke AT_KEYEXCHANGE.

Jika fungsi ini dipanggil sebagai bagian dari aplikasi yang diaktifkan CNG dan anggota dwKeySpec dari properti CERT_KEY_PROV_INFO_PROP_ID diatur ke -1, pilih sertifikat tempat NCRYPT_ALLOW_DECRYPT_FLAG atau NCRYPT_ALLOW_KEY_AGREEMENT_FLAG diatur.
CERT_SELECT_HARDWARE_ONLY
 Pilih sertifikat tempat nilai properti PP_IMPTYPE penyedia kunci privat terkait diatur ke CRYPT_IMPL_HARDWARE atau CRYPT_IMPL_REMOVABLE. (Untuk penyedia CNG, nilai properti NCRYPT_IMPL_TYPE_PROPERTY HARUS memiliki set NCRYPT_IMPL_HARDWARE_FLAG atau bit NCRYPT_IMPL_REMOVABLE_FLAG).

Jika fungsi ini dipanggil sebagai bagian dari aplikasi yang diaktifkan CNG, pilih sertifikat tempat properti NCRYPT_IMPL_TYPE_PROPERTY diatur ke NCRYPT_IMPL_HARDWARE_FLAG atau NCRYPT_IMPL_REMOVABLE_FLAG.
CERT_SELECT_ALLOW_DUPLICATES
 Izinkan pemilihan sertifikat tempat Subjek dan Nama Alt Subjek berisi informasi yang sama dan nilai ekstensi templat sertifikat setara. Secara default ketika sertifikat cocok dengan kriteria ini, hanya sertifikat terbaru yang dipilih.

[in, optional] pChainParameters

Penunjuk ke struktur CERT_SELECT_CHAIN_PARA untuk menentukan parameter untuk pembuatan rantai. Jika NULL, parameter default akan digunakan.

Anggota pChainPara dari struktur CERT_SELECT_CHAIN_PARA menunjuk ke struktur CERT_CHAIN_PARA yang dapat digunakan untuk mengaktifkan penandatanganan yang kuat.

[in] cCriteria

Jumlah elemen dalam array yang ditujukkan oleh array rgpCriteria .

[in, optional] rgpCriteria

Penunjuk ke array struktur CERT_SELECT_CRITERIA yang menentukan kriteria pilihan. Jika parameter ini diatur ke NULL, nilai parameter cCriteria harus nol.

[in] hStore

Handel ke penyimpanan untuk memilih sertifikat.

[out] pcSelection

Penunjuk ke nilai DWORD untuk menerima jumlah elemen dalam array yang ditujukkan oleh parameter pprgpSelection .

[out] pprgpSelection

Penunjuk ke penunjuk ke lokasi untuk menerima array struktur CERT_CHAIN_CONTEXT . Fungsi CertSelectCertificateChains hanya mengembalikan rantai sertifikat yang cocok dengan semua kriteria pilihan. Entri dalam array diurutkan berdasarkan kualitas, yaitu rantai dengan kualitas tertinggi adalah entri pertama.

Penyimpanan untuk array dialokasikan oleh fungsi CertSelectCertificateChains . Untuk membebaskan memori yang dialokasikan, Anda harus terlebih dahulu merilis setiap konteks rantai individual dalam array dengan memanggil fungsi CertFreeCertificateChain . Kemudian Anda harus membebaskan memori dengan memanggil fungsi CertFreeCertificateChainList .

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan TRUE.

Jika fungsi gagal, fungsi mengembalikan nol (FALSE). Untuk informasi kesalahan yang diperluas, panggil fungsi GetLastError .

Catatan Jika pilihan tidak menghasilkan hasil apa pun, fungsi CertSelectCertificateChains mengembalikan TRUE, tetapi nilai yang diarahkan oleh parameter pcSelection diatur ke nol.
 

Keterangan

Kriteria pilihan dapat ditentukan melalui parameter dwFlags , melalui parameter rgpCriteria , atau melalui kedua parameter. Jika tidak ada kriteria pilihan yang ditentukan, fungsi berhasil dan mengembalikan rantai sertifikat untuk semua sertifikat di penyimpanan yang ditentukan oleh parameter hStore .

Rantai sertifikat yang dipilih diurutkan berdasarkan logika preferensi berikut:

  • Lebih suka sertifikat yang merupakan sertifikat kartu pintar daripada sertifikat yang tidak berbasis kartu pintar.
  • Pilih sertifikat yang memiliki periode validitas yang lebih lama (tanggal kedaluwarsa nanti.)
  • Jika beberapa sertifikat memiliki tanggal kedaluwarsa yang sama, pilih sertifikat yang diterbitkan baru-baru ini.
  • Jika ada dasi, lebih suka rantai yang lebih pendek.
Kriteria pilihan tertentu mengharuskan rantai sertifikat dibuat sebelum Anda dapat memilih kriteria tersebut untuk digunakan. Jika sertifikat perantara yang diperlukan untuk membangun rantai tidak tersedia secara lokal, pengambilan jaringan dilakukan untuk sertifikat penerbit. Pengambilan jaringan ini dilakukan jika bendera CERT_SELECT_TRUSTED_ROOT diatur atau untuk kriteria berikut:
  • CERT_SELECT_BY_ISSUER_NAME
  • CERT_SELECT_BY_ISSUER_ATTR
  • CERT_SELECT_BY_POLICY_OID
Lakukan tindakan berikut untuk mengaktifkan pemeriksaan tanda tangan yang kuat:

Saat Anda mengaktifkan pemeriksaan tanda tangan yang kuat, rantai sertifikat apa pun yang mengembalikan kesalahan CERT_TRUST_IS_NOT_SIGNATURE_VALID di bidang dwErrorStatus dari struktur CERT_TRUST_STATUS akan dilewati. (Parameter pprgpSelection menunjuk ke struktur CERT_CHAIN_CONTEXT yang, pada gilirannya, menunjuk ke struktur CERT_TRUST_STATUS .) Nilai CERT_TRUST_HAS_WEAK_SIGNATURE juga diatur untuk tanda tangan yang lemah.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 7 [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2008 R2 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header wincrypt.h
Pustaka Crypt32.lib
DLL Crypt32.dll

Lihat juga

CertGetCertificateContextProperty

CertSetCertificateContextProperty