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.
| Valeur | Signification |
|---|---|
CERT_CHAIN_CACHE_END_CERT0x00000001 |
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_ONLY0x80000000 |
La vérification de la révocation accède uniquement aux URL mises en cache. Cela empêcherait la récupération réseau de listes de révocation de certificats ou OCSP pour les certificats de fin ou d’autorité de certification. CACHE_ONLY dépend d’un copain sur l’ordinateur pour avoir déjà récupéré la liste de révocation de certificats ou OCSP à partir du réseau. |
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT0x04000000 |
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) Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge. |
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL0x00000004 |
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, tels que les cabs CTL, les racines tierces et les émetteurs AIA. La plupart des racines doivent se trouver dans une ressource crypt32.dll. Si ce n’est pas le cas, cette récupération est nécessaire pour empêcher une erreur de génération de chaîne. Ces cabs et racines sont hébergés sur des serveurs Microsoft CDN hautes performances. 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. Normalement, les cabs CTL sont déjà pré-récupérés via le service cryptsvc. |
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 |
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_TRUST0x00000800 |
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_TRUST0x00000400 |
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 et Windows XP : Cet indicateur n’est pas pris en charge. |
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE0x00010000 |
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_CONTEXTS0x00000080 |
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 |
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE0x00000100 |
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_TIMEOUT0x08000000 |
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’attente 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_TIME0x00000200 |
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_AIA0x00002000 |
La définition de cet indicateur désactive explicitement les récupérations d’accès aux informations d’autorité (AIA). Parfois, les serveurs TLS sont configurés de manière incorrecte et n’incluent pas les certificats d’autorité de certification appropriés dans la négociation. |
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_CERT0x10000000 |
La vérification de la révocation est effectuée sur le certificat final et uniquement sur le certificat final. |
CERT_CHAIN_REVOCATION_CHECK_CHAIN0x20000000 |
La vérification de la révocation est effectuée sur tous les certificats de chaque chaîne. |
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT0x40000000 |
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 structureCERT_CHAIN_PARA pointée par le paramètrepChainPara . - 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 surNTE_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.
- Définissez la CERT_CHAIN_CACHE_END_CERT.
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 |