IBackgroundCopyServerCertificateValidationCallback ::ValidateServerCertificate, méthode (bits10_3.h)

Méthode de rappel que vous implémentez qui sera appelée afin de pouvoir valider les certificats de serveur envoyés lors de l’ouverture d’une connexion HTTPS.

Syntaxe

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

Paramètres

job

Type : IBackgroundCopyJob*

Le travail.

file

Type : IBackgroundCopyFile*

Fichier transféré.

certLength

Type : DWORD

Longueur en octets des données de certificat.

certData

Type : const BYTE []

Tableau d’octets contenant les données de certificat. Le nombre d’octets doit correspondre à certLength.

certEncodingType

Type : DWORD

Type d’encodage de certificat.

certStoreLength

Type : DWORD

Longueur en octets des données du magasin de certificats.

certStoreData

Type : const BYTE []

Tableau d’octets contenant les données du magasin de certificats. Le nombre d’octets doit correspondre à certStoreLength.

Valeur de retour

Retournez S_OK pour indiquer que le certificat est acceptable. Sinon, retournez tout HRESULTcode d’erreur pour indiquer que le certificat n’est pas acceptable.

Remarques

La validation de certificat est effectuée en deux phases. La première phase est la phase du système d’exploitation où le système d’exploitation effectue un ensemble standard de vérifications de validation sur le certificat. Après cela, si la phase du système d’exploitation transmet le certificat, votre rappel est appelé pour effectuer une validation supplémentaire.

Implémentez cette méthode de validation lorsque vous souhaitez effectuer vos propres vérifications sur le certificat de serveur. Vos propres vérifications sont en plus des vérifications normales de validation de certificat du système d’exploitation.

Si votre méthode de validation refuse le certificat, le travail passe à BG_JOB_STATE_TRANSIENT_ERROR avec un contexte d’erreur de travail de BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK et l’erreur HRESULT à partir de votre rappel. Si votre rappel n’a pas pu être appelé (par exemple, parce que BITS a besoin de valider un certificat de serveur après la sortie de votre programme), le code d’erreur du travail sera BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. Lorsque votre application est exécutée à la prochaine exécution, elle peut corriger cette erreur en définissant à nouveau le rappel de validation et en réexécutant le travail.

BITS appelle cette méthode de rappel uniquement si vous implémentez l’interface IBackgroundCopyServerCertificateValidationCallback et que vous la transmettez à IBackgroundCopyJobHttpOptions3 ::SetServerCertificateValidationInterface.

L’interface de validation devient non valide lorsque votre application se termine ; BITS ne conserve pas d’enregistrement de l’interface de validation. Par conséquent, le processus d’initialisation de votre application doit appeler SetServerCertificateValidationInterface sur ces travaux existants pour lesquels vous souhaitez recevoir des demandes de validation de certificat.

Si plusieurs applications appellent SetServerCertificateValidationInterface pour définir l’interface de notification du travail, la dernière application à appeler est celle qui recevra des notifications. Les autres applications ne recevront pas de notifications.

Voici les étapes générales pour valider un certificat. N’oubliez pas que ces étapes ne constituent qu’un exemple. La validation réelle est sous votre contrôle. En outre, les étapes 5-7 sont largement identiques à celles effectuées par le système d’exploitation pendant l’étape de validation du système d’exploitation.

1. Appelez CertCreateCertificateContext avec certEncodingType, certDataet certLength pour récupérer un CERT_CONTEXT.

2. Déclarez et initialisez une structure de CRYPT_DATA_BLOB (définie dans wincrypt.h) avec l’objet blob de mémoire sérialisé passé via certStoreLength et certStoreData.

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

3. Obtenez un handle dans la chaîne de certificats en appelant CertOpenStore avec CERT_STORE_PROV_SERIALIZED, 0, nullptr, indicateurs et pointeur vers le CRYPT_DATA_BLOB de l’étape 2.
4. Obtenez un pointeur vers un contexte de chaîne de certificats en appelant CertGetCertificateChain avec nullptr, certContext, nullptr, le handle de l’étape 3, les paramètres de chaîne, les indicateurs et nullptr.
5. Créez la stratégie de validation de certificat.

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. Appelez CertVerifyCertificateChainPolicy avec le type de stratégie, le contexte de chaîne, les paramètres de stratégie et l’état de la stratégie.
7. Convertissez l’erreur Win32 (policyStatus.dwError) en HRESULT et retournez-la.

Une description des comportements de mise en cache de validation BITS suit. BITS gère un cache par travail de certificats qui ont passé la validation personnalisée. Cela permet d’éviter une nouvelle validation redondante et potentiellement coûteuse au cours de la durée de vie du travail. Le cache se compose de <point de terminaison de serveur, de hachage de certificat> tuples, où point de terminaison est défini comme nom de serveur :port. Si un travail a déjà autorisé un certificat spécifique à partir d’un point de terminaison spécifique, le rappel ne sera plus appelé.

Bien sûr, le certificat devra passer la logique de validation du système d’exploitation à chaque tentative de connexion (vous pouvez personnaliser la logique de validation du système d’exploitation avec un appel à IBackgroundCopyJobHttpOptions ::SetSecurityFlags), qui traite les cas d’angle temporels tels que lorsque le certificat a été valide très récemment (en termes de secondes), mais il a expiré maintenant.

BITS ne met pas en cache les certificats considérés comme non valides par le rappel de validation fourni par l’application. Il est important que vous connaissiez toutes les tentatives de connexion infructueuses, afin de pouvoir détecter les déploiements malveillants au niveau de l’application. Par exemple, un certificat incorrect unique est beaucoup moins important que des milliers de certificats incorrects du même serveur.

Le cache de certificat d’un travail est effacé sur chaque appel à SetServerCertificateValidationInterface, car il indique que la logique de validation de certificat de serveur de l’application a changé.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 10, version 1809 [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2016 [applications de bureau uniquement]
d’en-tête	bits10_3.h (include Bits.h)
bibliothèque	Bits.lib
DLL	Bits.dll

Voir aussi

IBackgroundCopyJobHttpOptions3 ::SetServerCertificateValidationInterface