Metodo IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate (bits10_3.h)

Metodo di callback implementato che verrà chiamato in modo che sia possibile convalidare i certificati del server inviati quando viene aperta una connessione HTTPS.

Sintassi

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

Parametri

job

Tipo: IBackgroundCopyJob*

Processo.

file

Tipo: IBackgroundCopyFile*

Il file in corso di trasferimento.

certLength

Tipo: DWORD

Lunghezza in byte dei dati del certificato.

certData

Tipo: const BYTE []

Matrice di byte contenenti i dati del certificato. Il numero di byte deve corrispondere certLengtha .

certEncodingType

Tipo: DWORD

Tipo di codifica del certificato.

certStoreLength

Tipo: DWORD

Lunghezza in byte dei dati dell'archivio certificati.

certStoreData

Tipo: const BYTE []

Matrice di byte contenenti i dati dell'archivio certificati. Il numero di byte deve corrispondere certStoreLengtha .

Valore restituito

Restituire S_OK per indicare che il certificato è accettabile. In caso contrario, restituire qualsiasi codice di erroreHRESULT per indicare che il certificato non è accettabile.

Commenti

La convalida del certificato viene eseguita in due fasi. La prima fase è la fase del sistema operativo in cui il sistema operativo esegue un set standard di controlli di convalida sul certificato. In seguito, se la fase del sistema operativo supera il certificato, il callback verrà chiamato per eseguire una convalida aggiuntiva.

Implementare questo metodo di convalida quando si desidera eseguire controlli personalizzati sul certificato del server. I controlli personalizzati si aggiungono ai normali controlli di convalida del certificato del sistema operativo.

Se il metodo di convalida rifiuta il certificato, il processo passerà a BG_JOB_STATE_TRANSIENT_ERROR con un contesto di errore del processo di BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK e l'errore HRESULT dal callback. Se il callback non è stato chiamato (ad esempio, perché BITS deve convalidare un certificato server dopo l'uscita dal programma), il codice di errore del processo verrà BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. Quando l'applicazione viene eseguita successivamente, può correggere questo errore impostando nuovamente il callback di convalida e riprendendo il processo.

BITS chiama questo metodo di callback solo se si implementa l'interfaccia IBackgroundCopyServerCertificateValidationCallback e passarla in IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface.

L'interfaccia di convalida diventa non valida quando l'applicazione termina; BITS non mantiene un record dell'interfaccia di convalida. Di conseguenza, il processo di inizializzazione dell'applicazione deve chiamare SetServerCertificateValidationInterface nei processi esistenti per i quali si desidera ricevere richieste di convalida del certificato.

Se più di un'applicazione chiama SetServerCertificateValidationInterface per impostare l'interfaccia di notifica per il processo, l'ultima applicazione da chiamare è quella che riceverà le notifiche. Le altre applicazioni non riceveranno notifiche.

Ecco i passaggi generali per convalidare un certificato. Tenere presente che questi passaggi sono solo un esempio. La convalida effettiva è sotto il controllo. Inoltre, i passaggi da 5 a 7 sono in gran parte uguali a quelli che il sistema operativo esegue durante il passaggio di convalida del sistema operativo.

1. Chiamare CertCreateCertificateContext con certEncodingType, certDatae certLength per recuperare un CERT_CONTEXT.

2. Dichiarare e inizializzare una struttura CRYPT_DATA_BLOB (definita in wincrypt.h) con il BLOB di memoria serializzato passato tramite certStoreLength e certStoreData.

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

3. Ottenere un handle per la catena di certificati chiamando CertOpenStore con CERT_STORE_PROV_SERIALIZED, 0, nullptr, flag e puntatore alla CRYPT_DATA_BLOB dal passaggio 2.
4. Ottenere un puntatore a un contesto della catena di certificati chiamando CertGetCertificateChain con nullptr, certContext, nullptr, handle dal passaggio 3, parametri della catena, flag e nullptr.
5. Creare i criteri di convalida del certificato.

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. Chiamare CertVerifyCertificateChainPolicy con il tipo di criterio, il contesto della catena, i parametri dei criteri e lo stato dei criteri.
7. Convertire l'errore Win32 (policyStatus.dwError) in un HRESULT e restituirlo.

Di seguito è riportata una descrizione dei comportamenti di memorizzazione nella cache della convalida BITS. BITS gestisce una cache per processo di certificati che hanno superato la convalida personalizzata. Si tratta di evitare la ridondanza e potenzialmente costosa la rivalutazione nel corso della durata del processo. La cache è costituita da <endpoint server, tuple hash> certificato, dove l'endpoint è definito come nome server:port. Se un processo ha già consentito un certificato specifico da un endpoint specifico, il callback non verrà chiamato di nuovo.

Naturalmente, il certificato dovrà passare la logica di convalida del sistema operativo in ogni tentativo di connessione (è possibile personalizzare la logica di convalida del sistema operativo con una chiamata a IBackgroundCopyJobHttpOptions::SetSecurityFlags), che risolve casi di angolo sensibili al tempo, ad esempio quando il certificato è stato valido molto di recente (in termini di secondi), ma è scaduto ora.

BITS non memorizza nella cache i certificati considerati non validi dal callback di convalida fornito dall'app. È importante essere consapevoli di tutti i tentativi di connessione non riusciti, in modo da poter rilevare distribuzioni dannose a livello di app. Ad esempio, un certificato non valido è molto meno relativo a migliaia di certificati non valido dallo stesso server.

La cache dei certificati di un processo viene cancellata in ogni chiamata a SetServerCertificateValidationInterface, poiché indica che la logica di convalida del certificato server dell'app è stata modificata.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10, versione 1809 [solo app desktop]
Server minimo supportato	Windows Server 2016 [solo app desktop]
Intestazione	bits10_3.h (includere Bits.h)
Libreria	Bits.lib
DLL	Bits.dll

Vedi anche

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface