Fonction CertGetCertificateChain (wincrypt.h)

Article
07/16/2024

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.

Valeur	Signification
CERT_CHAIN_CACHE_END_CERT 0x00000001	Lorsque cet indicateur est défini, le certificat final est mis en cache, ce qui peut accélérer le processus de création de chaînes. Par défaut, le certificat final n’est pas mis en cache et il doit être vérifié chaque fois qu’une chaîne est générée pour elle.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY 0x80000000	La vérification de la révocation accède uniquement aux URL mises en cache.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT 0x04000000	Cet indicateur est utilisé en interne lors de la génération de chaînes pour un certificat d’état de certificat en ligne (OCSP) pour empêcher les vérifications de révocation cycliques. Lors de la génération de chaînes, si la réponse OCSP est signée par un signataire OCSP indépendant, puis, en plus de la build de chaîne d’origine, il existe une deuxième chaîne créée pour le certificat de signataire OCSP lui-même. Cet indicateur est utilisé pendant cette deuxième build de chaîne pour empêcher un certificat de signataire OCSP indépendant récursif. Si le certificat du signataire contient l’extension szOID_PKIX_OCSP_NOCHECK, la vérification de la révocation est ignorée pour le certificat de signataire feuille. Les vérifications OCSP et CRL sont autorisées. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL 0x00000004	Utilise uniquement les URL mises en cache dans la création d’une chaîne de certificats. Internet et intranet ne sont pas recherchés pour les objets basés sur l’URL. Remarque Cet indicateur n’est pas applicable à la vérification de révocation. Définissez CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY pour utiliser uniquement les URL mises en cache pour la vérification de révocation.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING 0x00000040	Pour des raisons de performances, la deuxième passe de la construction de chaînes considère uniquement les chemins de chaîne potentiels qui ont une qualité supérieure ou égale à la plus haute qualité déterminée pendant la première passe. La première passe prend uniquement en compte la signature valide, la chaîne complète et les racines approuvées pour calculer la qualité de la chaîne. Cet indicateur peut être défini pour désactiver cette optimisation et prendre en compte tous les chemins de chaîne potentiels pendant la deuxième passe.
CERT_CHAIN_DISABLE_MY_PEER_TRUST 0x00000800	Cet indicateur n’est pas pris en charge. Les certificats dans le magasin « My » ne sont jamais considérés comme étant approuvés par les pairs.
CERT_CHAIN_ENABLE_PEER_TRUST 0x00000400	Les certificats d’entité finale dans le magasin « TrustedPeople » sont approuvés sans effectuer de génération de chaîne. Cette fonction ne définit pas le CERT_TRUST_IS_PARTIAL_CHAIN ou CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus bits membres du paramètre ppChainContext. Windows Server 2003 Windows XP : cet indicateur n’est pas pris en charge.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE 0x00010000	La définition de cet indicateur indique que l’appelant souhaite opter pour des vérifications de signature faibles. Cet indicateur est disponible dans la mise à jour cumulative pour chaque système d’exploitation commençant par Windows 7 et Windows Server 2008 R2.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS 0x00000080	La valeur par défaut consiste à retourner uniquement le chemin de chaîne de qualité le plus élevé. La définition de cet indicateur retourne les chaînes de qualité inférieure. Ceux-ci sont retournés dans le cLowerQualityChainContext et rgpLowerQualityChainContext champs du contexte de chaîne.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE 0x00000100	La définition de cet indicateur empêche la mise à jour automatique des racines tierces à partir de Windows Update Web Server.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 0x08000000	Lorsque vous définissez CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT et que vous spécifiez également une valeur pour le membre dwUrlRetrievalTimeout de la structure CERT_CHAIN_PARA, la valeur que vous spécifiez dans dwUrlRetrievalTimeout représente le délai d’expiration cumulé sur toutes les récupérations d’URL de révocation. Si vous définissez CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT mais que vous ne spécifiez pas de valeur dwUrlRetrievalTimeout, le délai d’expiration cumulé maximal est défini par défaut sur 20 secondes. Chaque URL testée sera expirée après la moitié du solde cumulé restant. Autrement dit, la première URL expire après 10 secondes, la seconde après 5 secondes, la troisième après 2,5 secondes et ainsi de suite jusqu’à ce qu’une URL réussisse, 20 secondes ont réussi, ou il n’y a plus d’URL à tester. Si vous ne définissez pas CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, chaque URL de révocation de la chaîne est affectée à un délai maximal égal à la valeur spécifiée dans dwUrlRetrievalTimeout. Si vous ne spécifiez pas de valeur pour le membre dwUrlRetrievalTimeout membre, chaque URL de révocation reçoit un délai d’expiration par défaut maximal de 15 secondes. Si aucune URL ne réussit, la valeur maximale du délai d’expiration cumulée est de 15 secondes multipliée par le nombre d’URL de la chaîne. Vous pouvez définir les valeurs par défaut à l’aide de la stratégie de groupe.
CERT_CHAIN_TIMESTAMP_TIME 0x00000200	Lorsque cet indicateur est défini, pTime est utilisé comme heure d’horodatage pour déterminer si le certificat de fin était valide. L’heure actuelle peut également être utilisée pour déterminer si le certificat final reste valide. Toutes les autres autorité de certification (CA) et les certificats racines de la chaîne sont vérifiés à l’aide de l’heure actuelle et non pTime.
CERT_CHAIN_DISABLE_AIA 0x00002000	La définition de cet indicateur désactive explicitement les récupérations d’accès aux informations d’autorité (AIA).

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

Valeur	Signification
CERT_CHAIN_REVOCATION_CHECK_END_CERT 0x10000000	La vérification de la révocation est effectuée sur le certificat final et uniquement sur le certificat final.
CERT_CHAIN_REVOCATION_CHECK_CHAIN 0x20000000	La vérification de la révocation est effectuée sur tous les certificats de chaque chaîne.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT 0x40000000	La vérification de la révocation est effectuée sur tous les certificats de toutes les chaînes, à l’exception du certificat racine.

[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.

Exemples

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

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	wincrypt.h
bibliothèque	Crypt32.lib
DLL	Crypt32.dll