Fonction CryptVerifySignatureA (wincrypt.h)

Article
08/27/2023

Important Cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser les API de nouvelle génération de chiffrement. Microsoft peut supprimer cette API dans les versions ultérieures.

La fonction CryptVerifySignature vérifie la signature d’un objet de hachage.

Avant d’appeler cette fonction, CryptCreateHash doit être appelé pour créer le handle d’un objet de hachage. CryptHashData ou CryptHashSessionKey est ensuite utilisé pour ajouter des données ou des clés de session à l’objet de hachage.

Une fois CryptVerifySignature terminé, seul CryptDestroyHash peut être appelé à l’aide du handle hHash .

Syntaxe

BOOL CryptVerifySignatureA(
  [in] HCRYPTHASH hHash,
  [in] const BYTE *pbSignature,
  [in] DWORD      dwSigLen,
  [in] HCRYPTKEY  hPubKey,
  [in] LPCSTR     szDescription,
  [in] DWORD      dwFlags
);

Paramètres

[in] hHash

Handle de l’objet de hachage à vérifier.

[in] pbSignature

Adresse des données de signature à vérifier.

[in] dwSigLen

Nombre d’octets dans les données de signature pbSignature .

[in] hPubKey

Handle de la clé publique à utiliser pour authentifier la signature. Cette clé publique doit appartenir à la paire de clés qui a été utilisée à l’origine pour créer la signature numérique.

[in] szDescription

Ce paramètre ne doit plus être utilisé et doit être défini sur NULL pour empêcher les vulnérabilités de sécurité. Toutefois, il est toujours pris en charge pour la compatibilité descendante dans le fournisseur de chiffrement de base Microsoft.

[in] dwFlags

Les valeurs d’indicateur suivantes sont définies.

Valeur	Signification
CRYPT_NOHASHOID 0x00000001	Cet indicateur est utilisé avec les fournisseurs RSA. Lors de la vérification de la signature, l’identificateur d’objet de hachage (OID) n’est pas censé être présent ou vérifié. Si cet indicateur n’est pas défini, l’OID de hachage dans la signature par défaut est vérifié comme spécifié dans la définition de DigestInfo dans PKCS #7.
CRYPT_TYPE2_FORMAT 0x00000002	Cet indicateur n’est pas utilisé.
CRYPT_X931_FORMAT 0x00000004	Utilisez la prise en charge de X.931 pour la version compatible FIPS 186-2 de RSA (rDSA).

Valeur retournée

Si la fonction réussit, la valeur de retour est TRUE.

Si la fonction échoue, la valeur de retour est FALSE. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Les codes d’erreur préfacés par « NTE » sont générés par le fournisseur de solutions cloud que vous utilisez. Certains codes d’erreur possibles suivent.

Code de retour	Description
ERROR_INVALID_HANDLE	L’un des paramètres spécifie un handle qui n’est pas valide.
ERROR_INVALID_PARAMETER	L’un des paramètres contient une valeur qui n’est pas valide. Il s’agit le plus souvent d’un pointeur qui n’est pas valide.
NTE_BAD_FLAGS	Le paramètre dwFlags est différent de zéro.
NTE_BAD_HASH	L’objet de hachage spécifié par le paramètre hHash n’est pas valide.
NTE_BAD_KEY	Le paramètre hPubKey ne contient pas de handle pour une clé publique valide.
NTE_BAD_SIGNATURE	La signature n’était pas valide. Cela peut être dû au fait que les données elles-mêmes ont changé, que la chaîne de description ne correspond pas ou que la clé publique incorrecte a été spécifiée par hPubKey. Cette erreur peut également être retournée si les algorithmes de hachage ou de signature ne correspondent pas à ceux utilisés pour créer la signature.
NTE_BAD_UID	Le contexte du fournisseur de services de chiffrement (CSP) spécifié lors de la création de l’objet de hachage est introuvable.
NTE_NO_MEMORY	Le fournisseur de solutions cloud a manqué de mémoire pendant l’opération.

Remarques

La fonction CryptVerifySignature termine le hachage. Après cet appel, plus aucune donnée ne peut être ajoutée au hachage. Les appels supplémentaires à CryptHashData ou CryptHashSessionKey échouent. Une fois l’application terminée avec le hachage, CryptDestroyHash doit être appelé pour détruire l’objet de hachage.

Si vous générez une signature à l’aide des API .NET Framework et que vous essayez de la vérifier à l’aide de la fonction CryptVerifySignature , la fonction échoue et GetLastError retourne NTE_BAD_SIGNATURE. Cela est dû aux différents ordres d’octets entre l’API Win32 native et l’API .NET Framework.

L’API de chiffrement natif utilise l’ordre d’octets little-endian tandis que l’API .NET Framework utilise l’ordre d’octets big-endian. Si vous vérifiez une signature générée à l’aide d’une API .NET Framework, vous devez échanger l’ordre des octets de signature avant d’appeler la fonction CryptVerifySignature pour vérifier la signature.

Exemples

Pour obtenir un exemple qui utilise la fonction CryptVerifySignature , consultez Exemple de programme C : signature d’un hachage et vérification de la signature de hachage.

Notes

L’en-tête wincrypt.h définit CryptVerifySignature comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
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	Advapi32.lib
DLL	Advapi32.dll