CertSelectCertificateChains, fonction (wincrypt.h)

  • Article

La fonction CertSelectCertificateChains récupère les chaînes de certificats en fonction des critères de sélection spécifiés.

Syntaxe

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

Paramètres

[in, optional] pSelectionContext

Pointeur vers le GUID du scénario de sélection de certificat à utiliser pour cet appel.

[in] dwFlags

Indicateurs permettant de contrôler le processus de sélection de certificat. Ce paramètre peut être une combinaison de zéro ou plusieurs des indicateurs suivants :

Valeur Signification
CERT_SELECT_ALLOW_EXPIRED
 Sélectionnez les certificats expirés qui répondent aux critères de sélection. Par défaut, les certificats expirés sont rejetés de la sélection.
CERT_SELECT_TRUSTED_ROOT
 Sélectionnez les certificats sur lesquels le bit d’erreur dans le status d’approbation de la chaîne de certificats n’est pas défini sur CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN ou CERT_TRUST_IS_NOT_TIME_VALID.

En outre, les certificats qui présentent l’une des erreurs de contrainte non valide suivantes ne sont pas sélectionnés :

  • CERT_TRUST_INVALID_POLICY_CONSTRAINTS
  • CERT_TRUST_INVALID_BASIC_CONSTRAINTS
  • CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED
 Sélectionnez les certificats qui ne sont pas auto-émis et auto-signés.
CERT_SELECT_HAS_PRIVATE_KEY
 Sélectionnez les certificats dont la valeur est définie pour la propriété CERT_KEY_PROV_INFO_PROP_ID du certificat.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE
 Sélectionnez les certificats sur lesquels la valeur du membre dwKeySpec de la propriété CERT_KEY_PROV_INFO_PROP_ID est définie sur AT_SIGNATURE.

Si cette fonction est appelée dans le cadre d’une application activée par CNG et que le membre dwKeySpec de la propriété CERT_KEY_PROV_INFO_PROP_ID a la valeur -1, sélectionnez les certificats sur lesquels la valeur de la propriété NCRYPT_KEY_USAGE_PROPERTY de la clé privée associée a le NCRYPT_ALLOW_SIGNING_FLAG défini.
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE
 Sélectionnez les certificats sur lesquels la valeur du membre dwKeySpec de la propriété CERT_KEY_PROV_INFO_PROP_ID est définie sur AT_KEYEXCHANGE.

Si cette fonction est appelée dans le cadre d’une application compatible CNG et que le membre dwKeySpec de la propriété CERT_KEY_PROV_INFO_PROP_ID a la valeur -1, sélectionnez les certificats sur lesquels NCRYPT_ALLOW_DECRYPT_FLAG ou NCRYPT_ALLOW_KEY_AGREEMENT_FLAG est défini.
CERT_SELECT_HARDWARE_ONLY
 Sélectionnez des certificats sur lesquels la valeur de la propriété PP_IMPTYPE du fournisseur de clé privée associé est définie sur CRYPT_IMPL_HARDWARE ou CRYPT_IMPL_REMOVABLE. (Pour les fournisseurs CNG, NCRYPT_IMPL_TYPE_PROPERTY valeur de propriété DOIT avoir le NCRYPT_IMPL_HARDWARE_FLAG ou NCRYPT_IMPL_REMOVABLE_FLAG bit défini).

Si cette fonction est appelée dans le cadre d’une application activée par CNG, sélectionnez des certificats sur lesquels la propriété NCRYPT_IMPL_TYPE_PROPERTY est définie sur NCRYPT_IMPL_HARDWARE_FLAG ou NCRYPT_IMPL_REMOVABLE_FLAG.
CERT_SELECT_ALLOW_DUPLICATES
 Autorisez la sélection de certificats sur lesquels l’objet et le nom de l’objet contiennent les mêmes informations et la valeur d’extension du modèle de certificat est équivalente. Par défaut, lorsque les certificats correspondent à ce critère, seul le certificat le plus récent est sélectionné.

[in, optional] pChainParameters

Pointeur vers une structure de CERT_SELECT_CHAIN_PARA pour spécifier des paramètres pour la génération de chaînes. Si la valeur est NULL, les paramètres par défaut sont utilisés.

Le membre pChainPara de la structure CERT_SELECT_CHAIN_PARA pointe vers une structure CERT_CHAIN_PARA qui peut être utilisée pour activer la signature forte.

[in] cCriteria

Nombre d’éléments dans le tableau pointé vers le tableau rgpCriteria .

[in, optional] rgpCriteria

Pointeur vers un tableau de structures CERT_SELECT_CRITERIA qui définissent les critères de sélection. Si ce paramètre est défini sur NULL, la valeur du paramètre cCriteria doit être égale à zéro.

[in] hStore

Handle vers un magasin à partir duquel sélectionner les certificats.

[out] pcSelection

Pointeur vers une valeur DWORD pour recevoir le nombre d’éléments dans le tableau vers lequel pointe le paramètre pprgpSelection .

[out] pprgpSelection

Pointeur vers un pointeur vers un emplacement pour recevoir un tableau de CERT_CHAIN_CONTEXT structure. La fonction CertSelectCertificateChains retourne uniquement les chaînes de certificats qui correspondent à tous les critères de sélection. Les entrées du tableau sont classées par qualité, c’est-à-dire que la chaîne avec la qualité la plus élevée est la première entrée.

Le stockage du tableau est alloué par la fonction CertSelectCertificateChains . Pour libérer la mémoire allouée, vous devez d’abord libérer chaque contexte de chaîne individuel dans le tableau en appelant la fonction CertFreeCertificateChain . Vous devez libérer la mémoire en appelant la fonction CertFreeCertificateChainList .

Valeur retournée

Si la fonction réussit, la fonction retourne TRUE.

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

Note Si la sélection ne produit aucun résultat, la fonction CertSelectCertificateChains retourne TRUE, mais la valeur pointée par le paramètre pcSelection est définie sur zéro.
 

Remarques

Les critères de sélection peuvent être spécifiés par le biais du paramètre dwFlags , du paramètre rgpCriteria ou des deux paramètres. Si aucun critère de sélection n’est spécifié, la fonction réussit et retourne des chaînes de certificats pour tous les certificats dans le magasin spécifié par le paramètre hStore .

Les chaînes de certificats sélectionnées sont triées en fonction de la logique de préférence suivante :

  • Préférez les certificats carte intelligents aux certificats qui ne sont pas basés sur des carte intelligents.
  • Préférez les certificats dont la période de validité est plus longue (la date d’expiration est ultérieure).)
  • Si plusieurs certificats ont la même date d’expiration, préférez les certificats qui ont été émis plus récemment.
  • S’il y a une cravate, préférez les chaînes plus courtes.
Certains critères de sélection nécessitent la création d’une chaîne de certificats avant de pouvoir sélectionner ces critères à utiliser. Si les certificats intermédiaires requis pour générer la chaîne ne sont pas disponibles localement, une récupération réseau est effectuée pour les certificats d’émetteur. Cette récupération réseau est effectuée si l’indicateur CERT_SELECT_TRUSTED_ROOT est défini ou pour les critères suivants :
  • CERT_SELECT_BY_ISSUER_NAME
  • CERT_SELECT_BY_ISSUER_ATTR
  • CERT_SELECT_BY_POLICY_OID
Effectuez les actions suivantes pour activer la vérification forte des signatures :
  • Créez une structure CERT_STRONG_SIGN_PARA , spécifiez les paramètres de signature forte requis et définissez un pointeur vers la structure dans le membre pStrongSignPara d’une structure CERT_CHAIN_PARA .
  • Définissez un pointeur vers la structure CERT_CHAIN_PARA dans le membre pChainPara d’une structure CERT_SELECT_CHAIN_PARA .
  • Définissez un pointeur vers la structure CERT_SELECT_CHAIN_PARA dans le paramètre pChainParameters de cette fonction (CertSelectCertificateChains).

Lorsque vous activez la vérification forte des signatures, toute chaîne de certificats qui retourne une erreur de CERT_TRUST_IS_NOT_SIGNATURE_VALID dans le champ dwErrorStatus de la structure CERT_TRUST_STATUS est ignorée. (Le paramètre pprgpSelection pointe vers une structure CERT_CHAIN_CONTEXT qui, à son tour, pointe vers la structure CERT_TRUST_STATUS .) La valeur CERT_TRUST_HAS_WEAK_SIGNATURE est également définie pour une signature faible.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 7 [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2008 R2 [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête wincrypt.h
Bibliothèque Crypt32.lib
DLL Crypt32.dll

Voir aussi

CertGetCertificateContextProperty

CertSetCertificateContextProperty