Freigeben über

IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate-Methode (bits10_3.h)

  • Artikel

Eine Rückrufmethode, die Sie implementieren, die aufgerufen wird, damit Sie die beim Öffnen einer HTTPS-Verbindung gesendeten Serverzertifikate überprüfen können.

Syntax

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

Parameter

job

Typ: IBackgroundCopyJob*

Der Auftrag.

file

Typ: IBackgroundCopyFile-*

Die Datei, die übertragen wird.

certLength

Typ: DWORD-

Die Länge in Byte der Zertifikatdaten.

certData

Typ: BYTE- []

Ein Array von Bytes, die die Zertifikatdaten enthalten. Die Anzahl der Bytes muss certLengthübereinstimmen.

certEncodingType

Typ: DWORD-

Der Zertifikatcodierungstyp.

certStoreLength

Typ: DWORD-

Die Länge in Byte der Zertifikatspeicherdaten.

certStoreData

Typ: BYTE- []

Ein Array von Bytes, die die Zertifikatspeicherdaten enthalten. Die Anzahl der Bytes muss certStoreLengthübereinstimmen.

Rückgabewert

Geben Sie S_OK zurück, um anzugeben, dass das Zertifikat akzeptabel ist. Geben Sie andernfalls HRESULT-Fehlercode zurück,, um anzugeben, dass das Zertifikat nicht akzeptabel ist.

Bemerkungen

Die Zertifikatüberprüfung erfolgt in zwei Phasen. Die erste Phase ist die Betriebssystemphase (Betriebssystem), in der das Betriebssystem einen Standardsatz von Überprüfungen für das Zertifikat durchführt. Danach wird ihr Rückruf aufgerufen, wenn die Betriebssystemphase das Zertifikat übergibt, um eine zusätzliche Überprüfung durchzuführen.

Implementieren Sie diese Überprüfungsmethode, wenn Sie eigene Prüfungen für das Serverzertifikat durchführen möchten. Ihre eigenen Prüfungen sind zusätzlich zu den normalen Überprüfungen der Betriebssystemzertifikate.

Wenn die Validierungsmethode das Zertifikat ablehnt, wechselt der Auftrag mit einem Auftragsfehlerkontext von BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK zu BG_JOB_STATE_TRANSIENT_ERROR und der Fehler HRESULT- aus dem Rückruf. Wenn Ihr Rückruf nicht aufgerufen werden konnte (z. B. weil BITS zum Überprüfen eines Serverzertifikats nach dem Beenden des Programms erforderlich ist), wird der Auftragsfehlercode BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. Wenn die Anwendung als nächstes ausgeführt wird, kann dieser Fehler behoben werden, indem sie den Überprüfungsrückruf erneut festlegen und den Auftrag fortsetzen.

BITS ruft diese Rückrufmethode nur auf, wenn Sie die IBackgroundCopyServerCertificateValidationCallback Schnittstelle implementieren und an IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterfaceübergeben.

Die Überprüfungsschnittstelle wird ungültig, wenn die Anwendung beendet wird. BITS verwaltet keinen Datensatz der Überprüfungsschnittstelle. Daher sollte der Initialisierungsprozess Ihrer Anwendung SetServerCertificateValidationInterface für diese vorhandenen Aufträge aufrufen, für die Sie Zertifikatüberprüfungsanforderungen erhalten möchten.

Wenn mehrere Anwendungen SetServerCertificateValidationInterface aufrufen, um die Benachrichtigungsschnittstelle für den Auftrag festzulegen, wird die letzte Anwendung aufgerufen, die Benachrichtigungen empfängt. Die anderen Anwendungen erhalten keine Benachrichtigungen.

Hier sind die allgemeinen Schritte zum Überprüfen eines Zertifikats. Beachten Sie, dass diese Schritte nur ein Beispiel sind. Die tatsächliche Überprüfung befindet sich unter Ihrer Kontrolle. Außerdem sind die Schritte 5-7 weitgehend identisch mit der Funktionsweise des Betriebssystems während des Betriebssystemüberprüfungsschritts.

  1. Rufen Sie CertCreateCertificateContext mit certEncodingType, certDataund certLength auf, um eine CERT_CONTEXTabzurufen.

  2. Deklarieren und initialisieren Sie eine CRYPT_DATA_BLOB-Struktur (definiert in wincrypt.h), wobei das serialisierte Speicher-BLOB über certStoreLength und certStoreDataübergeben wird.

DATA_BLOB storeData{};
storeData.cbData = certStoreLength;
storeData.pbData = const_cast<PBYTE>(certStoreData);
  1. Rufen Sie ein Handle für die Zertifikatkette ab, indem Sie CertOpenStore- mit CERT_STORE_PROV_SERIALIZED, 0, nullptr, Flags und einem Zeiger auf die CRYPT_DATA_BLOB aus Schritt 2 aufrufen.
  2. Rufen Sie einen Zeiger auf einen Zertifikatkettenkontext ab, indem Sie CertGetCertificateChain mit nullptr, certContext, nullptr, dem Handle aus Schritt 3, Kettenparametern, Flags und Nullptr aufrufen.
  3. Erstellen Sie die Zertifikatüberprüfungsrichtlinie.
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;
  1. Rufen Sie CertVerifyCertificateChainPolicy mit Richtlinientyp, Kettenkontext, Richtlinienparametern und Richtlinienstatus auf.
  2. Konvertieren Sie den Win32-Fehler (policyStatus.dwError) in ein HRESULT, und geben Sie diesen zurück.

Eine Beschreibung des BitS-Überprüfungszwischenspeicherungsverhaltens folgt. BITS verwaltet einen Cache pro Auftrag von Zertifikaten, die eine benutzerdefinierte Überprüfung bestanden haben. Dies besteht darin, redundante und potenziell teure erneute Überprüfungen über die Lebensdauer des Auftrags zu vermeiden. Der Cache besteht aus <Serverendpunkt, Zertifikathash-> Tupel, wobei Endpunkt- als Servername:portdefiniert ist. Wenn ein Auftrag bereits ein bestimmtes Zertifikat von einem bestimmten Endpunkt zugelassen hat, wird der Rückruf nicht erneut aufgerufen.

Natürlich muss das Zertifikat die Betriebssystemüberprüfungslogik für jeden Verbindungsversuch durchlaufen (Sie können die Betriebssystemüberprüfungslogik mit einem Aufruf von IBackgroundCopyJobHttpOptions::SetSecurityFlags) anpassen, in dem zeitempfindliche Eckfälle behandelt werden, z. B. wann das Zertifikat in letzter Zeit (in Bezug auf Sekunden) gültig war, aber jetzt abgelaufen ist.

BITS speichert keine Zertifikate zwischen, die vom von der App bereitgestellten Überprüfungsrückruf als ungültig eingestuft werden. Es ist wichtig, dass Sie alle erfolglosen Verbindungsversuche kennen, damit Sie schädliche Bereitstellungen auf App-Ebene erkennen können. Beispielsweise ist ein einmaliges fehlerhaftes Zertifikat viel weniger betroffen als Tausende von ungültigen Zertifikaten vom selben Server.

Der Zertifikatcache eines Auftrags wird für jeden Aufruf von SetServerCertificateValidationInterfacegelöscht, da die Logik für die Serverzertifikatüberprüfung der App geändert wurde.

Anforderungen

Anforderung Wert
mindestens unterstützte Client- Windows 10, Version 1809 [nur Desktop-Apps]
mindestens unterstützte Server- Windows Server 2016 [nur Desktop-Apps]
Header- bits10_3.h (bits.h einschließen)
Library Bits.lib
DLL- Bits.dll

Siehe auch

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface