Share via

IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate-Methode (bits10_3.h)

  • Artikel

Eine von Ihnen implementierte Rückrufmethode, die aufgerufen wird, damit Sie die Serverzertifikate überprüfen können, die beim Öffnen einer HTTPS-Verbindung gesendet werden.

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 zu übertragende Datei.

certLength

Typ: DWORD

Die Länge der Zertifikatdaten in Bytes.

certData

Typ: const BYTE []

Ein Array von Bytes, das die Zertifikatdaten enthält. Die Anzahl der Bytes muss mit übereinstimmen certLength.

certEncodingType

Typ: DWORD

Der Zertifikatcodierungstyp.

certStoreLength

Typ: DWORD

Die Länge des Zertifikatspeichers in Bytes.

certStoreData

Typ: const BYTE []

Ein Array von Bytes, das das Zertifikat enthält, speichert Daten. Die Anzahl der Bytes muss mit übereinstimmen certStoreLength.

Rückgabewert

Geben Sie S_OK zurück, um anzugeben, dass das Zertifikat akzeptabel ist. Andernfalls geben Sie einen beliebigen HRESULT-Fehlercode zurück, um anzugeben, dass das Zertifikat nicht akzeptabel ist.

Hinweise

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

Implementieren Sie diese Validierungsmethode, wenn Sie eigene Überprüfungen für das Serverzertifikat durchführen möchten. Ihre eigenen Überprüfungen werden zusätzlich zu den normalen Überprüfungen des Betriebssystemzertifikats durchgeführt.

Wenn Ihre Validierungsmethode das Zertifikat ablehnt, wechselt der Auftrag zu BG_JOB_STATE_TRANSIENT_ERROR mit einem Auftragsfehlerkontext von BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK und dem Fehler HRESULT aus Ihrem Rückruf. Wenn Ihr Rückruf nicht aufgerufen werden konnte (z. B. weil BITS ein Serverzertifikat überprüfen musste, nachdem das Programm beendet wurde), wird der Auftragsfehlercode BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. Wenn Ihre Anwendung das nächste Mal ausgeführt wird, kann sie diesen Fehler beheben, 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 Validierungsschnittstelle wird ungültig, wenn Ihre Anwendung beendet wird. BITS verwaltet keine Aufzeichnung der Validierungsschnittstelle. Daher sollte der Initialisierungsprozess Ihrer Anwendung SetServerCertificateValidationInterface für die vorhandenen Aufträge aufrufen, für die Sie Zertifikatüberprüfungsanforderungen erhalten möchten.

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

Hier finden Sie die allgemeinen Schritte zum Überprüfen eines Zertifikats. Beachten Sie, dass diese Schritte nur ein Beispiel sind. Die tatsächliche Überprüfung wird von Ihnen gesteuert. Außerdem sind die Schritte 5 bis 7 weitgehend identisch mit dem, was das Betriebssystem während des Betriebssystemüberprüfungsschritts ausführt.

  1. Rufen Sie CertCreateCertificateContext mit certEncodingType, und auf, certDataum certLength eine CERT_CONTEXT abzurufen.

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

DATA_BLOB storeData{};
storeData.cbData = certStoreLength;
storeData.pbData = const_cast<PBYTE>(certStoreData);
  1. Rufen Sie ein Handle auf 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 Richtlinien status auf.
  2. Konvertieren Sie den Win32-Fehler (policyStatus.dwError) in ein HRESULT, und geben Sie diesen zurück.

Es folgt eine Beschreibung des Bits-Validierungs-Zwischenspeicherungsverhaltens. BITS verwaltet einen Auftragscache mit Zertifikaten, die eine benutzerdefinierte Überprüfung bestanden haben. Dadurch wird eine redundante und potenziell teure erneute Überprüfung über die Lebensdauer des Auftrags vermieden. Der Cache besteht <aus Serverendpunkt, Zertifikathashtupeln> , wobei der Endpunkt als Servername:Port definiert 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 bei jedem Verbindungsversuch durchlaufen (Sie können die Betriebssystemüberprüfungslogik mit einem Aufruf von IBackgroundCopyJobHttpOptions::SetSecurityFlags anpassen), die zeitabhängige Eckfälle behandelt, z. B. wann das Zertifikat erst kürzlich (in Sekunden) gültig war, aber es ist jetzt abgelaufen.

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 fehlgeschlagenen Verbindungsversuche kennen, damit Sie schädliche Bereitstellungen auf App-Ebene erkennen können. Beispielsweise ist ein einmaliges fehlerhaftes Zertifikat viel weniger beunruhigend als Tausende von fehlerhaften Zertifikaten vom gleichen Server.

Der Zertifikatcache eines Auftrags wird bei jedem Aufruf von SetServerCertificateValidationInterface gelöscht, da er angibt, dass sich die Logik der Serverzertifikatüberprüfung der App geändert hat.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 10, Version 1809 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2016 [nur Desktop-Apps]
Kopfzeile bits10_3.h (Bits.h einschließen)
Bibliothek Bits.lib
DLL Bits.dll

Weitere Informationen

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface