Condividi tramite

Metodo IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate (bits10_3.h)

  • Articolo

Metodo di callback implementato che verrà chiamato in modo da poter convalidare i certificati del server inviati all'apertura di 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*

File da trasferire.

certLength

Tipo: DWORD

Lunghezza in byte dei dati del certificato.

certData

Tipo: BYTE []

Matrice di byte contenente i dati del certificato. Il numero di byte deve corrispondere certLength.

certEncodingType

Tipo: DWORD

Tipo di codifica del certificato.

certStoreLength

Tipo: DWORD

Lunghezza in byte dei dati dell'archivio certificati.

certStoreData

Tipo: BYTE []

Matrice di byte contenente i dati dell'archivio certificati. Il numero di byte deve corrispondere certStoreLength.

Valore restituito

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

Osservazioni

La convalida dei certificati 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. Successivamente, 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 non è stato possibile chiamare il callback, ad esempio perché BITS è necessario per convalidare un certificato server dopo la chiusura del programma, il codice di errore del processo verrà BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. Quando l'applicazione viene eseguita successivamente, può correggere l'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 la si passa all'interfaccia IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface.

L'interfaccia di convalida non è valida quando l'applicazione termina; BITS non gestisce un record dell'interfaccia di convalida. Di conseguenza, il processo di inizializzazione dell'applicazione deve chiamare SetServerCertificateValidationInterface su tali processi esistenti per cui 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 a chiamarla è 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 gli stessi di ciò 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 di 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);
  1. Ottenere un handle per la catena di certificati chiamando CertOpenStore con CERT_STORE_PROV_SERIALIZED, 0, nullptr, flag e un puntatore al CRYPT_DATA_BLOB del passaggio 2.
  2. Ottenere un puntatore a un contesto della catena di certificati chiamando CertGetCertificateChain con nullptr, certContext, nullptr, handle del passaggio 3, parametri della catena, flag e nullptr.
  3. 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;
  1. Chiamare CertVerifyCertificateChainPolicy con tipo di criteri, contesto della catena, parametri dei criteri e stato dei criteri.
  2. Convertire l'errore Win32 (policyStatus.dwError) in 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. Ciò consente di evitare la rivalutazione ridondante e potenzialmente costosa per tutta la durata del processo. La cache è costituita da <endpoint server, tuple hash del certificato>, in cui endpoint è definito come nome server:porta. 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 ritenuti non validi dal callback di convalida fornito dall'app. È importante conoscere 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 inferiore a migliaia di certificati non valido dallo stesso server.

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

Fabbisogno

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 (include Bits.h)
libreria Bits.lib
dll Bits.dll

Vedere anche

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface