Fonction CertVerifyCTLUsage (wincrypt.h)
La fonction CertVerifyCTLUsage vérifie qu’un sujet est approuvé pour une utilisation spécifiée en recherchant une liste d’approbation de certificats (CTL) signée et valide dans le temps avec les identificateurs d’utilisation qui contiennent l’objet. L’objet d’un certificat peut être identifié par son contexte de certificat ou par un identificateur unique tel que le hachage SHA1 du certificat de l’objet.
Syntaxe
BOOL CertVerifyCTLUsage(
[in] DWORD dwEncodingType,
[in] DWORD dwSubjectType,
[in] void *pvSubject,
[in] PCTL_USAGE pSubjectUsage,
[in] DWORD dwFlags,
[in, optional] PCTL_VERIFY_USAGE_PARA pVerifyUsagePara,
[in, out] PCTL_VERIFY_USAGE_STATUS pVerifyUsageStatus
);
Paramètres
[in] dwEncodingType
Spécifie le type d’encodage utilisé. Actuellement, seuls les X509_ASN_ENCODING et les PKCS_7_ASN_ENCODING sont utilisés; toutefois, des types d’encodage supplémentaires peuvent être ajoutés à l’avenir. Pour l’un ou l’autre type d’encodage actuel, utilisez
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING.
[in] dwSubjectType
Si le paramètre dwSubjectType a la valeur CTL_CERT_SUBJECT_TYPE, pvSubject pointe vers une structure CERT_CONTEXT . Le membre SubjectAlgorithm de la structure est examiné pour déterminer la représentation de l’identité du sujet. Initialement, seuls les hachages SHA1 et MD5 sont pris en charge en tant que valeurs pour SubjectAlgorithm. La propriété de hachage appropriée est obtenue à partir de la structure CERT_CONTEXT .
Si le paramètre dwSubjectType a la valeur CTL_ANY_SUBJECT_TYPE, pvSubject pointe vers la structure CTL_ANY_SUBJECT_INFO . Le membre SubjectAlgorithm de cette structure doit correspondre au type d’algorithme de la CTL, et le membre SubjectIdentifier doit correspondre à l’une des entrées CTL.
Si dwSubjectType a la valeur précédente, dwEncodingType n’est pas utilisé.
[in] pvSubject
Valeur utilisée conjointement avec le paramètre dwSubjectType .
[in] pSubjectUsage
Pointeur vers une structure CTL_USAGE utilisée pour spécifier l’utilisation prévue du sujet.
[in] dwFlags
Si le CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG n’est pas défini, une CTL dont l’heure n’est plus valide dans l’un des magasins spécifiés par rghCtlStore dans CTL_VERIFY_USAGE_PARA peut être remplacée. En cas de remplacement, le CERT_VERIFY_UPDATED_CTL_FLAG est défini dans le membre dwFlags de pVerifyUsageStatus. Si cet indicateur est défini, une mise à jour n’est pas effectuée, même si une CTL mise à jour est reçue pour une CTL qui se trouve dans le magasin et dont l’heure n’est plus valide.
Si le CERT_VERIFY_TRUSTED_SIGNERS_FLAG est défini, seuls les magasins de signataire spécifiés par rghSignerStore dans CTL_VERIFY_USAGE_PARA sont recherchés pour trouver le signataire. Sinon, les magasins de signataire fournissent des sources supplémentaires pour rechercher le certificat du signataire. Pour plus d'informations, consultez la section Notes.
Si CERT_VERIFY_NO_TIME_CHECK_FLAG est défini, les listes de contrôle client ne sont pas vérifiées pour la durée de validité. Sinon, ils le sont.
Si CERT_VERIFY_ALLOW_MORE_USAGE_FLAG est défini, la CTL peut contenir des identificateurs d’utilisation en plus de ceux spécifiés par pSubjectUsage. Sinon, la CTL trouvée ne contiendra pas d’identificateurs d’utilisation supplémentaires.
[in, optional] pVerifyUsagePara
Pointeur vers une structure de CTL_VERIFY_USAGE_PARA qui spécifie les magasins à rechercher pour rechercher la CTL et les magasins qui contiennent des signataires de la CTL acceptables. La définition du membre ListIdentifier limite davantage la recherche.
[in, out] pVerifyUsageStatus
Pointeur vers une structure CTL_VERIFY_USAGE_STATUS . Le membre cbSize de la structure doit être défini sur la taille, en octets, de la structure, et tous les autres champs doivent être définis sur zéro avant l’appel de CertVerifyCTLUsage . Pour plus d’informations, consultez CTL_VERIFY_USAGE_STATUS.
Valeur retournée
Si le sujet est approuvé pour l’utilisation spécifiée, TRUE est retourné. Dans le cas contraire, FALSE est retourné. GetLastError peut retourner l’un des codes d’erreur suivants.
| Valeur | Description |
|---|---|
|
Aucune DLL ou fonction exportée n’a été trouvée pour vérifier l’utilisation du sujet. |
|
La fonction appelée n’a pas pu effectuer une case activée d’utilisation sur le sujet. |
|
Le serveur était hors connexion ; par conséquent, la fonction appelée n’a pas pu terminer l’utilisation case activée. |
|
Le sujet n’a pas été trouvé dans une CTL. |
|
Aucun signataire approuvé n’a été trouvé pour vérifier la signature du message ou de la liste d’approbation. |
Le membre dwError du CTL_VERIFY_USAGE_PARA pointé par pVerifyUsageStatus est défini sur le même code d’erreur.
Remarques
CertVerifyCTLUsage est un répartiteur pour les fonctions qui peuvent être installées à l’aide d’un identificateur d’objet (OID). Tout d’abord, il tente de trouver une fonction OID qui correspond au premier identificateur d’objet d’utilisation dans la structure CLT_USAGE pointée par pSubjectUsage. En cas d’échec, il utilise les fonctions CertDllVerifyCTLUsage par défaut.
La fonction CertDllVerifyCTLUsage dans Cryptnet.dll peut être installée à l’aide d’un OID ; il possède les propriétés suivantes :
- Si les magasins CTL sont spécifiés par rghCtlStore dans pVerifyUsagePara, seules ces magasins sont recherchés pour trouver une CTL. Sinon, le magasin de système d’approbation fait l’objet d’une recherche pour trouver une CTL.
- Si CERT_VERIFY_TRUSTED_SIGNERS_FLAG est défini, seuls les magasins du signataire spécifiés par rghSignerStore dans pVerifyUsagePara sont recherchés pour rechercher le certificat correspondant à l’émetteur et au numéro de série du signataire. Sinon, le magasin du message CTL, les magasins du signataire spécifiés par rghSignerStore dans pVerifyUsagePara, le magasin de système d’approbation, le magasin système d’autorité de certification, ROOT et les magasins système de certificats d’éditeur de logiciels (SPC) sont recherchés pour rechercher le certificat du signataire. Dans les deux cas, la clé publique dans le certificat trouvé est utilisée pour vérifier la signature de la CTL.
- Si la CTL a un membre NextUpdate défini et que CERT_VERIFY_NO_TIME_CHECK n’est pas défini, elle est vérifiée pour la durée de validité.
- Si la CTL obtenue à partir du magasin a une heure qui n’est pas valide, une tentative d’obtention d’une version de durée valide est effectuée. La fonction CertDllVerifyCTLUsage utilise la propriété NextUpdateLocation ou l’extension NextUpdateLocation de la CTL, ou recherche dans les informations du signataire un attribut NextUpdateLocation .
Configuration requise
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | wincrypt.h |
| Bibliothèque | Crypt32.lib |
| DLL | Crypt32.dll |
Voir aussi
Fonctions de vérification à l’aide de listes de contrôle cloud