Fungsi WinVerifyTrust (wintrust.h)

Artikel
07/21/2023

Fungsi WinVerifyTrust melakukan tindakan verifikasi kepercayaan pada objek tertentu. Fungsi meneruskan pertanyaan ke penyedia kepercayaan yang mendukung pengidentifikasi tindakan, jika ada.

Untuk verifikasi sertifikat, gunakan fungsi CertGetCertificateChain dan CertVerifyCertificateChainPolicy .

Sintaks

LONG WinVerifyTrust(
  [in] HWND   hwnd,
  [in] GUID   *pgActionID,
  [in] LPVOID pWVTData
);

Parameter

[in] hwnd

Handel opsional ke jendela penelepon. Penyedia kepercayaan dapat menggunakan nilai ini untuk menentukan apakah ia dapat berinteraksi dengan pengguna. Namun, penyedia kepercayaan biasanya melakukan tindakan verifikasi tanpa input dari pengguna.

Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
INVALID_HANDLE_VALUE	Tidak ada pengguna interaktif. Penyedia kepercayaan melakukan tindakan verifikasi tanpa bantuan pengguna.
Nol	Penyedia kepercayaan dapat menggunakan desktop interaktif untuk menampilkan antarmuka penggunanya.
Handel jendela yang valid	Penyedia kepercayaan dapat memperlakukan nilai apa pun selain INVALID_HANDLE_VALUE atau nol sebagai handel jendela yang valid yang dapat digunakan untuk berinteraksi dengan pengguna.

[in] pgActionID

Penunjuk ke struktur GUID yang mengidentifikasi tindakan dan penyedia kepercayaan yang mendukung tindakan tersebut. Nilai ini menunjukkan jenis tindakan verifikasi yang akan dilakukan pada struktur yang ditunjukkan oleh pWinTrustData.

Layanan WinTrust dirancang untuk bekerja dengan penyedia kepercayaan yang diterapkan oleh pihak ketiga. Setiap penyedia kepercayaan menyediakan serangkaian pengidentifikasi tindakan uniknya sendiri. Untuk informasi tentang pengidentifikasi tindakan yang didukung oleh penyedia kepercayaan, lihat dokumentasi untuk penyedia kepercayaan tersebut.

Misalnya, Microsoft menyediakan Penyedia Kepercayaan Penerbit Perangkat Lunak yang dapat membangun kepercayaan perangkat lunak yang diunduh dari Internet atau beberapa jaringan publik lainnya. Penyedia Kepercayaan Penerbit Perangkat Lunak mendukung pengidentifikasi tindakan berikut. Konstanta ini didefinisikan dalam Softpub.h.

Nilai	Makna
DRIVER_ACTION_VERIFY	Verifikasi keaslian driver yang ditandatangani Windows Hardware Quality Labs (WHQL). Ini adalah penyedia kebijakan add-on Authenticode.
HTTPSPROV_ACTION	Verifikasi koneksi SSL/TLS melalui Internet Explorer.
OFFICESIGN_ACTION_VERIFY	ID Tindakan ini tidak didukung. Verifikasi keaslian file penyimpanan terstruktur dengan menggunakan penyedia kebijakan add-on Microsoft Office Authenticode. Windows Server 2003 dan Windows XP: ID Tindakan ini didukung.
WINTRUST_ACTION_GENERIC_CHAIN_VERIFY	Verifikasi rantai sertifikat yang dibuat dari jenis objek apa pun. Panggilan balik disediakan untuk menerapkan kebijakan rantai akhir dengan menggunakan konteks rantai untuk setiap penanda tangan dan penanda tangan penghitung.
WINTRUST_ACTION_GENERIC_VERIFY_V2	Verifikasi file atau objek menggunakan penyedia kebijakan Authenticode.
WINTRUST_ACTION_TRUSTPROVIDER_TEST	Tulis struktur CRYPT_PROVIDER_DATA ke file setelah memanggil penyedia kebijakan Authenticode.

[in] pWVTData

Pointer yang, saat ditransmisikan sebagai struktur WINTRUST_DATA , berisi informasi yang dibutuhkan penyedia kepercayaan untuk memproses pengidentifikasi tindakan yang ditentukan. Biasanya, struktur mencakup informasi yang mengidentifikasi objek yang harus dievaluasi oleh penyedia kepercayaan.

Format struktur tergantung pada pengidentifikasi tindakan. Untuk informasi tentang data yang diperlukan untuk pengidentifikasi tindakan tertentu, lihat dokumentasi untuk penyedia kepercayaan yang mendukung tindakan tersebut.

Nilai kembali

Jika penyedia kepercayaan memverifikasi bahwa subjek dipercaya untuk tindakan yang ditentukan, nilai yang dikembalikan adalah nol. Tidak ada nilai lain selain nol yang harus dianggap sebagai pengembalian yang berhasil.

Jika penyedia kepercayaan tidak memverifikasi bahwa subjek dipercaya untuk tindakan yang ditentukan, fungsi mengembalikan kode status dari penyedia kepercayaan.

Catatan Nilai yang dikembalikan adalah LONG, bukan HRESULT seperti yang didokumenkan sebelumnya. Jangan gunakan makro HRESULT seperti BERHASIL untuk menentukan apakah fungsi berhasil. Sebagai gantinya, periksa nilai yang dikembalikan untuk kesetaraan ke nol.

Misalnya, penyedia kepercayaan mungkin menunjukkan bahwa subjek tidak tepercaya, atau tepercaya tetapi dengan batasan atau peringatan. Nilai yang dikembalikan dapat berupa nilai khusus penyedia kepercayaan yang dijelaskan dalam dokumentasi untuk penyedia kepercayaan individu, atau bisa menjadi salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
TRUST_E_SUBJECT_NOT_TRUSTED	Subjek gagal dalam tindakan verifikasi yang ditentukan. Sebagian besar penyedia kepercayaan mengembalikan kode kesalahan yang lebih rinci yang menjelaskan alasan kegagalan tersebut. Catatan Kode pengembalian TRUST_E_SUBJECT_NOT_TRUSTED dapat dikembalikan tergantung pada nilai kunci registri EnableCertPaddingCheck di bawah HKLM\Software\Microsoft\Cryptography\Wintrust\Config. Jika EnableCertPaddingCheck diatur ke "1", maka pemeriksaan tambahan dilakukan untuk memverifikasi bahwa struktur WIN_CERTIFICATE tidak berisi informasi asing. Pemeriksaan memvalidasi bahwa tidak ada data bukan nol di luar struktur PKCS #7. Untuk informasi lebih lanjut, silakan merujuk ke saran keamanan berikut: http://technet.microsoft.com/security/advisory/2915720#section1.
TRUST_E_PROVIDER_UNKNOWN	Penyedia kepercayaan tidak dikenal pada sistem ini.
TRUST_E_ACTION_UNKNOWN	Penyedia kepercayaan tidak mendukung tindakan yang ditentukan.
TRUST_E_SUBJECT_FORM_UNKNOWN	Penyedia kepercayaan tidak mendukung formulir yang ditentukan untuk subjek.

Keterangan

Fungsi WinVerifyTrust memungkinkan aplikasi memanggil penyedia kepercayaan untuk memverifikasi bahwa objek tertentu memenuhi kriteria operasi verifikasi yang ditentukan. Parameter pgActionID mengidentifikasi operasi verifikasi, dan parameter pWinTrustData mengidentifikasi objek yang kepercayaannya akan diverifikasi. Penyedia kepercayaan adalah DLL yang terdaftar dengan sistem operasi. Panggilan ke WinVerifyTrust meneruskan panggilan ke penyedia kepercayaan terdaftar, jika ada, yang mendukung pengidentifikasi tindakan yang ditentukan.

Misalnya, Penyedia Kepercayaan Penerbit Perangkat Lunak dapat memverifikasi bahwa file gambar yang dapat dieksekusi berasal dari penerbit perangkat lunak tepercaya dan bahwa file belum dimodifikasi sejak diterbitkan. Dalam hal ini, parameter pWinTrustData menentukan nama file dan jenis file, seperti file gambar Microsoft Portable Executable .

Setiap penyedia kepercayaan mendukung serangkaian tindakan tertentu yang dapat dievaluasi. Setiap tindakan memiliki GUID yang mengidentifikasinya. Penyedia kepercayaan dapat mendukung sejumlah pengidentifikasi tindakan, tetapi dua penyedia kepercayaan tidak dapat mendukung pengidentifikasi tindakan yang sama.

Untuk contoh yang menunjukkan cara menggunakan fungsi ini untuk memverifikasi tanda tangan file portable executable (PE), lihat Contoh Program C: Memverifikasi Tanda Tangan File PE.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	wintrust.h (termasuk Softpub.h)
Pustaka	Wintrust.lib
DLL	Wintrust.dll