Fonction CertGetCertificateChain (wincrypt.h)

La fonction CertGetCertificateChain génère un contexte de chaîne de certificats à partir d’un certificat final et retourne, le cas échéant, à un certificat racine approuvé.

Syntaxe

BOOL CertGetCertificateChain(
  [in, optional] HCERTCHAINENGINE     hChainEngine,
  [in]           PCCERT_CONTEXT       pCertContext,
  [in, optional] LPFILETIME           pTime,
  [in]           HCERTSTORE           hAdditionalStore,
  [in]           PCERT_CHAIN_PARA     pChainPara,
  [in]           DWORD                dwFlags,
  [in]           LPVOID               pvReserved,
  [out]          PCCERT_CHAIN_CONTEXT *ppChainContext
);

Paramètres

[in, optional] hChainEngine

Handle du moteur de chaîne (espace de noms et cache) à utiliser. Si hChainEngine est NULL, le moteur de chaîne par défaut, HCCE_CURRENT_USER, est utilisé. Ce paramètre peut être défini sur HCCE_LOCAL_MACHINE.

[in] pCertContext

Pointeur vers la CERT_CONTEXT du certificat final, certificat pour lequel une chaîne est générée. Ce contexte de certificat sera l’élément zero-index dans la première chaîne simple.

[in, optional] pTime

Pointeur vers une variable FILETIME qui indique l’heure de validation de la chaîne. Notez que l’heure n’affecte pas la vérification de la liste d’approbation, de la révocation ou du magasin racine. L’heure système actuelle est utilisée si NULL est passée à ce paramètre. La confiance dans un certificat particulier étant une racine approuvée est basée sur l’état actuel du magasin racine et non l’état du magasin racine à un moment passé par ce paramètre. Pour la révocation, une liste de révocation de certificats (CRL), elle-même, doit être valide à l’heure actuelle. La valeur de ce paramètre est utilisée pour déterminer si un certificat répertorié dans une liste de révocation de certificats a été révoqué.

[in] hAdditionalStore

Handle vers n’importe quel magasin supplémentaire pour rechercher des certificats de prise en charge et listes d’approbation de certificats (CTL). Ce paramètre peut être NULL si aucun magasin supplémentaire n’est à rechercher.

[in] pChainPara

Pointeur vers une structure CERT_CHAIN_PARA qui inclut des paramètres de génération de chaînes.

[in] dwFlags

Valeurs d’indicateur qui indiquent un traitement spécial. Ce paramètre peut être une combinaison d’un ou plusieurs des indicateurs suivants.

Vous pouvez également définir les indicateurs de révocation suivants, mais un seul indicateur de ce groupe peut être défini à la fois.

[in] pvReserved

Ce paramètre est réservé et doit être NULL.

[out] ppChainContext

Adresse d’un pointeur vers le contexte de chaîne créé. Lorsque vous avez terminé d’utiliser le contexte de chaîne, relâchez la chaîne en appelant la fonction CertFreeCertificateChain.

Valeur de retour

Si la fonction réussit, la fonction retourne une valeur différente de zéro (TRUE).

Si la fonction échoue, elle retourne zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Lorsqu’une application demande une chaîne de certificats, la structure retournée est sous la forme d’un CERT_CHAIN_CONTEXT. Ce contexte contient un tableau de structures CERT_SIMPLE_CHAIN où chaque chaîne simple passe d’un certificat final à un certificat auto-signé. Le contexte de chaîne connecte des chaînes simples via des listes d’approbation. Chaque chaîne simple contient la chaîne de certificats, les informations d’approbation récapitulatives sur la chaîne et les informations d’approbation sur chaque élément de certificat de la chaîne.

Les remarques suivantes s’appliquent à la vérification de signature forte :

• Vous pouvez activer la vérification de signature forte pour cette fonction en définissant le membre pStrongSignPara CERT_CHAIN_PARA de la structure CERT_CHAIN_PARA pointée par le paramètre pChainPara.
• Si un certificat sans signature forte est trouvé dans la chaîne, les erreurs CERT_TRUST_HAS_WEAK_SIGNATURE et CERT_TRUST_IS_NOT_SIGNATURE_VALID sont définies dans le champ dwErrorStatus de la structure CERT_TRUST_STATUS. Le paramètre ppChainContext pointe vers une structure CERT_CHAIN_CONTEXT qui, à son tour, pointe vers la structure CERT_TRUST_STATUS.
• Si la chaîne est forte signée, la clé publique dans le certificat final est vérifiée pour déterminer s’il répond aux exigences minimales de longueur de clé publique pour une signature forte. Si la condition n’est pas satisfaite, les erreurs CERT_TRUST_HAS_WEAK_SIGNATURE et CERT_TRUST_IS_NOT_SIGNATURE_VALID sont définies dans le champ dwErrorStatus de la structure CERT_TRUST_STATUS. Pour désactiver la vérification de la longueur de clé, définissez la valeur CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG dans le dwStrongSignFlags membre de la structure CERT_CHAIN_PARA pointée par le paramètre pChainPara.
• Si les indicateurs CERT_STRONG_SIGN_ENABLE_CRL_CHECK ou CERT_STRONG_SIGN_ENABLE_OCSP_CHECK sont définis dans la structure CERT_STRONG_SIGN_SERIALIZED_INFO et qu’une réponse CRL ou OCSP est trouvée sans signature forte, la liste de révocation de certificats ou la réponse OCSP est traitée comme étant hors connexion. Autrement dit, les erreurs CERT_TRUST_IS_OFFLINE_REVOCATION et CERT_TRUST_REVOCATION_STATUS_UNKNOWN sont définies dans le champ dwErrorStatus de la structure CERT_TRUST_STATUS. En outre, le membre dwRevocationResult de la structure CERT_REVOCATION_INFO est défini sur NTE_BAD_ALGID.

Les recommandations suivantes s’appliquent à toute application Windows appelant ces API pour vérifier un certificat d’authentification de serveur TLS :

• Activez uniquement la vérification de révocation pour le certificat final.
  • Définissez CERT_CHAIN_REVOCATION_CHECK_END_CERT indicateur.
  • La plupart des certificats d’autorité de certification ont la liste de révocation de certificats avec une validité temporelle de 1 à 6 mois.
    • Étant donné que les listes de révocation de certificats téléchargés sont mises en cache, cette validité est trop longue pour avoir beaucoup de valeur.
  • S’il existe une compromission de l’autorité de certification, le ou les certificats sont également ajoutés à la durée de vie CTL non autorisée de Windows
  • La pratique recommandée pour les serveurs TLS consiste à prendre en charge l’atapage OCSP pour le certificat final.
    • Dans ce cas, aucune récupération réseau n’est nécessaire, sauf si la réponse OCSP a expiré.
• Activez les récupérations réseau pour les listes de révocation de certificats, OCSP, les émetteurs AIA et les racines de la plateforme Windows CTL et tierces.
  • Lorsque la CERT_CHAIN_REVOCATION_CHECK_END_CERT ci-dessus est définie, il s’agit de la valeur par défaut.
  • Ne définissez aucun des indicateurs suivants pour empêcher les récupérations réseau. Pour plus d’informations sur ces indicateurs, consultez le tableau dwFlags ci-dessus :
    • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
    • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
    • CERT_CHAIN_DISABLE_AIA
• Activez le délai d’accumulation pour la liste de révocation de certificats et les récupérations réseau OCSP.
  • Définissez l’indicateur CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT passé à CertGetCertificateChain.
  • Fournit une limite supérieure sur le temps total autorisé pour la liste de révocation de certificats et les récupérations réseau OCSP.
• Réduisez la durée maximale autorisée pour chaque récupération réseau de 15 à 10 secondes.
  • Définissez le champ dwUrlRetrievalTimeout dans le CERT_CHAIN_PARA passé à CertGetCertificateChain sur 10 * 1000 millisecondes.
  • Cela réduit également le délai d’expiration cumulé de 20 à 10 secondes.
    • Seules les réponses OCSP doivent être téléchargées pour les certificats finaux. 5 secondes doivent être suffisantes pour ce téléchargement.
• Ignorez les erreurs de révocation hors connexion.
  • Définissez CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS dans le CERT_CHAIN_POLICY_PARA passé à CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL).
  • La récupération du réseau d’OCSP et de la liste de révocation de certificats est la meilleure tentative. La plupart des récupérations réseau doivent réussir en quelques secondes, mais il n’est pas garanti de 100%.
• Informations de validation de certificat de fin du cache.
  • Définissez la CERT_CHAIN_CACHE_END_CERT.
    • Permet la mise en cache LRU des informations sur les certificats finaux en plus des certificats intermédiaires.
  • Il est courant d’établir plusieurs connexions TLS au même serveur.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Exemple de programme C : création d’une chaîne de certificats.

Exigences

Voir aussi

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

fonctions de vérification de la chaîne de certificats