Metode IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate (bits10_3.h)

Metode panggilan balik yang Anda terapkan yang akan dipanggil sehingga Anda dapat memvalidasi sertifikat server yang dikirim saat koneksi HTTPS dibuka.

Sintaks

HRESULT ValidateServerCertificate(
  IBackgroundCopyJob  *job,
  IBackgroundCopyFile *file,
  DWORD               certLength,
  const BYTE []       certData,
  DWORD               certEncodingType,
  DWORD               certStoreLength,
  const BYTE []       certStoreData
);

Parameter

job

Jenis: IBackgroundCopyJob*

Pekerjaan itu.

file

Jenis: IBackgroundCopyFile*

File sedang ditransfer.

certLength

Jenis: DWORD

Panjang byte data sertifikat.

certData

Jenis: const BYTE []

Array byte yang berisi data sertifikat. Jumlah byte harus cocok certLengthdengan .

certEncodingType

Jenis: DWORD

Jenis pengodean sertifikat.

certStoreLength

Jenis: DWORD

Panjang byte data penyimpanan sertifikat.

certStoreData

Jenis: const BYTE []

Array byte yang berisi data penyimpanan sertifikat. Jumlah byte harus cocok certStoreLengthdengan .

Menampilkan nilai

Kembalikan S_OK untuk menunjukkan bahwa sertifikat dapat diterima. Jika tidak, kembalikan kode kesalahanHRESULT apa pun untuk menunjukkan bahwa sertifikat tidak dapat diterima.

Keterangan

Validasi sertifikat dilakukan dalam dua fase. Fase pertama adalah fase sistem operasi (OS) di mana OS melakukan serangkaian pemeriksaan validasi standar pada sertifikat. Setelah itu, jika fase OS melewati sertifikat, panggilan balik Anda akan dipanggil untuk melakukan validasi tambahan.

Terapkan metode validasi ini ketika Anda ingin melakukan pemeriksaan Anda sendiri pada sertifikat server. Pemeriksaan Anda sendiri adalah tambahan untuk pemeriksaan validasi sertifikat OS normal.

Jika metode validasi Anda menolak sertifikat, pekerjaan akan beralih ke BG_JOB_STATE_TRANSIENT_ERROR dengan konteks kesalahan pekerjaan BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK dan kesalahan HRESULT dari panggilan balik Anda. Jika panggilan balik Anda tidak dapat dipanggil (misalnya, karena BITS perlu memvalidasi sertifikat server setelah program Anda keluar), kode kesalahan pekerjaan akan BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. Ketika aplikasi Anda dijalankan berikutnya, aplikasi dapat memperbaiki kesalahan ini dengan mengatur panggilan balik validasi lagi dan melanjutkan pekerjaan.

BITS memanggil metode panggilan balik ini hanya jika Anda menerapkan antarmuka IBackgroundCopyServerCertificateValidationCallback dan meneruskannya ke IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface.

Antarmuka validasi menjadi tidak valid ketika aplikasi Anda dihentikan; BITS tidak mempertahankan catatan antarmuka validasi. Akibatnya, proses inisialisasi aplikasi Anda harus memanggil SetServerCertificateValidationInterface pada pekerjaan yang ada yang ingin Anda terima permintaan validasi sertifikatnya.

Jika lebih dari satu aplikasi memanggil SetServerCertificateValidationInterface untuk mengatur antarmuka pemberitahuan untuk pekerjaan tersebut, aplikasi terakhir yang memanggilnya adalah aplikasi yang akan menerima pemberitahuan. Aplikasi lain tidak akan menerima pemberitahuan.

Berikut adalah langkah-langkah umum untuk memvalidasi sertifikat. Ketahuilah bahwa langkah-langkah ini hanyalah contoh. Validasi aktual berada di bawah kendali Anda. Selain itu, langkah 5-7 sebagian besar sama dengan apa yang dilakukan OS selama langkah validasi OS.

1. Panggil CertCreateCertificateContext dengan certEncodingType, certData, dan certLength untuk mengambil CERT_CONTEXT.

2. Deklarasikan dan inisialisasi struktur CRYPT_DATA_BLOB (didefinisikan dalam wincrypt.h) dengan blob memori berseri yang diteruskan melalui certStoreLength dan certStoreData.

DATA_BLOB storeData{};
storeData.cbData = certStoreLength;
storeData.pbData = const_cast<PBYTE>(certStoreData);

3. Dapatkan handel ke rantai sertifikat dengan memanggil CertOpenStore dengan CERT_STORE_PROV_SERIALIZED, 0, nullptr, bendera, dan pointer ke CRYPT_DATA_BLOB dari langkah 2.
4. Dapatkan pointer ke konteks rantai sertifikat dengan memanggil CertGetCertificateChain dengan nullptr, certContext, nullptr, handel dari langkah 3, parameter rantai, bendera, dan nullptr.
5. Buat kebijakan validasi sertifikat.

CERT_CHAIN_POLICY_PARA policyParams{};
policyParams.cbSize = sizeof(policyParams);
policyParams.dwFlags =
    CERT_CHAIN_POLICY_IGNORE_NOT_TIME_VALID_FLAG |
    CERT_CHAIN_POLICY_IGNORE_WRONG_USAGE_FLAG |
    CERT_CHAIN_POLICY_IGNORE_INVALID_NAME_FLAG |
    CERT_CHAIN_POLICY_ALLOW_UNKNOWN_CA_FLAG;

6. Panggil CertVerifyCertificateChainPolicy dengan jenis kebijakan, konteks rantai, parameter kebijakan, dan status kebijakan.
7. Konversikan kesalahan Win32 (policyStatus.dwError) ke HRESULT dan kembalikan.

Deskripsi perilaku penembolokan validasi BITS berikut. BITS mempertahankan cache sertifikat per pekerjaan yang telah lulus validasi kustom. Ini untuk menghindari validasi ulang yang berlebihan dan berpotensi mahal selama masa pakai pekerjaan. Cache terdiri dari <titik akhir server, tuple hash> sertifikasi, di mana titik akhir didefinisikan sebagai nama server:port. Jika pekerjaan telah mengizinkan sertifikat tertentu dari titik akhir tertentu, maka panggilan balik tidak akan dipanggil lagi.

Tentu saja, sertifikat harus melewati logika validasi OS pada setiap upaya koneksi (Anda dapat menyesuaikan logika validasi OS dengan panggilan ke IBackgroundCopyJobHttpOptions::SetSecurityFlags), yang membahas kasus sudut sensitif waktu seperti ketika sertifikat valid sangat baru-baru ini (dalam hal detik), tetapi telah kedaluwarsa sekarang.

BITS tidak menyimpan sertifikat yang dianggap tidak valid oleh panggilan balik validasi yang disediakan aplikasi. Penting bagi Anda untuk mengetahui semua upaya koneksi yang gagal, sehingga Anda dapat mendeteksi penyebaran berbahaya di tingkat aplikasi. Misalnya, sertifikat buruk satu kali jauh lebih sedikit memprihatinkan daripada ribuan sertifikat buruk dari server yang sama.

Cache sertifikat pekerjaan dibersihkan pada setiap panggilan ke SetServerCertificateValidationInterface, karena menunjukkan bahwa logika validasi sertifikat server aplikasi telah berubah.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10, versi 1809 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2016 [hanya aplikasi desktop]
Header	bits10_3.h (termasuk Bits.h)
Pustaka	Bits.lib
DLL	Bits.dll

Lihat juga

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface