Fonction CertGetCertificateChain (wincrypt.h)
La fonction CertGetCertificateChain génère un contexte de chaîne de certificats à partir d’un certificat de fin et en remontant, si possible, à 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 a la valeur 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 le CERT_CONTEXT du certificat de fin, le certificat pour lequel une chaîne est générée. Ce contexte de certificat sera l’élément zéro 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 liste d’approbation, la révocation ou la vérification du magasin racine. L’heure système actuelle est utilisée si null est passé à ce paramètre. L’approbation d’un certificat particulier étant une racine approuvée est basée sur l’état actuel du magasin racine et non sur 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
Un handle vers n’importe quel magasin supplémentaire pour rechercher des certificats et des listes d’approbation de certificats (CTL) de prise en charge. Ce paramètre peut avoir la valeur NULL si aucune banque supplémentaire ne doit faire l’objet d’une recherche.
[in] pChainPara
Pointeur vers une structure CERT_CHAIN_PARA qui inclut des paramètres de génération de chaîne.
[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 |
|---|---|
|
Lorsque cet indicateur est défini, le certificat de fin est mis en cache, ce qui peut accélérer le processus de création de chaîne. Par défaut, le certificat de fin n’est pas mis en cache et il doit être vérifié chaque fois qu’une chaîne est créée pour lui. |
|
La vérification de révocation accède uniquement aux URL mises en cache. |
|
Cet indicateur est utilisé en interne lors de la génération de chaînes pour un certificat de signataire OCSP (Certificat status Protocol) en ligne afin d’empêcher les vérifications de révocation cycliques. Pendant la génération de chaîne, si la réponse OCSP est signée par un signataire OCSP indépendant, alors, en plus de la build de chaîne d’origine, une deuxième chaîne est créée pour le certificat de signataire OCSP lui-même. Cet indicateur est utilisé lors de cette deuxième génération de chaîne pour inhiber un certificat de signataire OCSP indépendant récursif. Si le certificat de signataire contient l’extension szOID_PKIX_OCSP_NOCHECK , la vérification de la révocation est ignorée pour le certificat de signataire feuille. La vérification OCSP et CRL est autorisée.
Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge. |
|
Utilise uniquement les URL mises en cache dans la création d’une chaîne de certificats. Internet et intranet ne font pas l’objet d’une recherche d’objets basés sur une URL.
Note Cet indicateur ne s’applique pas à 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 la révocation. |
|
Pour des raisons de performances, le deuxième passage de la construction de chaîne ne prend en compte que les chemins de chaîne potentiels dont la qualité est supérieure ou égale à la qualité la plus élevée déterminée lors du premier passage. 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 lors de la deuxième passe. |
|
Cet indicateur n’est pas pris en charge. Les certificats du magasin « Mon » ne sont jamais pris en compte pour l’approbation des homologues. |
|
Les certificats d’entité de fin 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_ROOT bits membres dwErrorStatus du paramètre ppChainContext. Windows Server 2003 Windows XP : Cet indicateur n’est pas pris en charge. |
|
La définition de cet indicateur indique que l’appelant souhaite accepter les vérifications de signature faibles.
Cet indicateur est disponible dans la mise à jour cumulative pour chaque système d’exploitation à partir de Windows 7 et Windows Server 2008 R2. |
|
La valeur par défaut consiste à renvoyer uniquement le chemin de chaîne de qualité la plus élevée. La définition de cet indicateur renvoie les chaînes de qualité inférieure. Elles sont retournées dans les champs cLowerQualityChainContext et rgpLowerQualityChainContext du contexte de chaîne. |
|
La définition de cet indicateur empêche la mise à jour automatique des racines tierces à partir du serveur web Windows Update. |
|
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’attente cumulé pour toutes les récupérations d’URL de révocation.
Si vous définissez CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT mais 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 expire une fois que la moitié du solde cumulé restant est passée. 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 sont passées, 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 se voit attribuer un délai d’attente maximal égal à la valeur spécifiée dans dwUrlRetrievalTimeout. Si vous ne spécifiez pas de valeur pour le membre dwUrlRetrievalTimeout , chaque URL de révocation se voit attribuer un délai d’expiration par défaut maximal de 15 secondes. Si aucune URL ne réussit, la valeur de délai d’expiration cumulée maximale est de 15 secondes multipliée par le nombre d’URL dans la chaîne. Vous pouvez définir les valeurs par défaut à l’aide de stratégie de groupe. |
|
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 de fin reste valide. Tous les autres certificats d’autorité de certification et racines de la chaîne sont vérifiés à l’aide de l’heure actuelle et non de pTime. |
|
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.
[in] pvReserved
Ce paramètre est réservé et doit avoir la valeur NULL.
[out] ppChainContext
Adresse d’un pointeur vers le contexte de chaîne créé. Une fois que vous avez terminé d’utiliser le contexte de chaîne, relâchez la chaîne en appelant la fonction CertFreeCertificateChain .
Valeur retournée
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 de fin à 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, des informations d’approbation récapitulatives sur la chaîne et des informations d’approbation sur chaque élément de certificat dans la chaîne.
Les remarques suivantes s’appliquent à la vérification de signature forte :
- Vous pouvez activer la vérification forte des signatures pour cette fonction en définissant le membre pStrongSignPara de la structure CERT_CHAIN_PARA vers laquelle pointe 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 signée de manière forte, la clé publique dans le certificat final est vérifiée pour déterminer si elle répond aux exigences minimales de longueur de clé publique pour une signature forte. Si la condition n’est pas remplie, 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 la clé, définissez la valeur CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG dans le membre dwStrongSignFlags de la structure CERT_CHAIN_PARA pointée vers le paramètre pChainPara .
- Si les indicateurs de CERT_STRONG_SIGN_ENABLE_CRL_CHECK ou de CERT_STRONG_SIGN_ENABLE_OCSP_CHECK sont définis dans la structure CERT_STRONG_SIGN_SERIALIZED_INFO et qu’une réponse de liste de révocation de révocation de certificats ou d’OCSP est trouvée sans signature forte, la réponse de la liste de révocation de certificats ou 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.
Configuration requise
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | wincrypt.h |
| Bibliothèque | Crypt32.lib |
| DLL | Crypt32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour