CryptVerifySignatureA-Funktion (wincrypt.h)

Artikel
11/20/2024

Wichtige Diese API ist veraltet. Neue und vorhandene Software sollten mit der Verwendung Kryptografie-APIs der nächsten Generation beginnen. Microsoft kann diese API in zukünftigen Versionen entfernen.

Die CryptVerifySignature--Funktion überprüft die Signatur eines Hashobjekts.

Vor dem Aufrufen dieser Funktion muss CryptCreateHash aufgerufen werden, um das Handle eines Hashobjekts zu erstellen. CryptHashData oder CryptHashSessionKey wird dann verwendet, um dem Hashobjekt Daten oder Sitzungsschlüssel hinzuzufügen.

Nachdem CryptVerifySignature abgeschlossen abgeschlossen ist, können nur CryptDestroyHash- mithilfe des hHash Handle aufgerufen werden.

Syntax

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

Parameter

[in] hHash

Ein Handle zum Überprüfen des Hashobjekts.

[in] pbSignature

Die Adresse der zu überprüfenden Signaturdaten.

[in] dwSigLen

Die Anzahl der Bytes in der pbSignature Signaturdaten.

[in] hPubKey

Ein Handle für den öffentlichen Schlüssel, mit dem die Signatur authentifiziert werden soll. Dieser öffentliche Schlüssel muss zum Schlüsselpaar gehören, das ursprünglich zum Erstellen der digitalen Signaturverwendet wurde.

[in] szDescription

Dieser Parameter sollte nicht mehr verwendet werden und muss auf NULL- festgelegt werden, um Sicherheitsrisiken zu verhindern. Es wird jedoch weiterhin aus Gründen der Abwärtskompatibilität im Microsoft Base-Kryptografieanbieter unterstützt.

[in] dwFlags

Die folgenden Flagwerte werden definiert.

Wert	Bedeutung
CRYPT_NOHASHOID 0x00000001	Dieses Flag wird bei RSA-Anbietern verwendet. Beim Überprüfen der Signatur wird erwartet, dass der Hash Objektbezeichner (OID) nicht vorhanden oder überprüft wird. Wenn dieses Flag nicht festgelegt ist, wird das Hash-OID in der Standardsignatur wie in der Definition von DigestInfo in PKCS #7 angegeben überprüft.
CRYPT_TYPE2_FORMAT 0x00000002	Dieses Kennzeichen wird nicht verwendet.
CRYPT_X931_FORMAT 0x00000004	Verwenden Sie die X.931-Unterstützung für die FIPS 186-2-kompatible Version von RSA (rDSA).

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE. Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.

Die von "NTE" vorangestellten Fehlercodes werden von dem verwendeten CSP generiert. Einige mögliche Fehlercodes folgen.

Rückgabecode	Beschreibung
ERROR_INVALID_HANDLE	Einer der Parameter gibt ein ungültiges Handle an.
ERROR_INVALID_PARAMETER	Einer der Parameter enthält einen ungültigen Wert. Dies ist am häufigsten ein ungültiger Zeiger.
NTE_BAD_FLAGS	Der dwFlags Parameter ist nonzero.
NTE_BAD_HASH	Das vom hHash Parameter angegebene Hashobjekt ist ungültig.
NTE_BAD_KEY	Der hPubKey--Parameter enthält kein Handle für einen gültigen öffentlichen Schlüssel.
NTE_BAD_SIGNATURE	Die Signatur war ungültig. Dies kann darauf zurückzuführen sein, dass die Daten selbst geändert wurden, die Beschreibungszeichenfolge nicht übereinstimmte oder der falsche öffentliche Schlüssel von hPubKeyangegeben wurde. Dieser Fehler kann auch zurückgegeben werden, wenn die Hashing- oder Signaturalgorithmen nicht mit den Signaturalgorithmen übereinstimmen, die zum Erstellen der Signatur verwendet werden.
NTE_BAD_UID	Der kryptografischen Dienstanbieter Kontext (CSP), der beim Erstellen des Hashobjekts angegeben wurde, kann nicht gefunden werden.
NTE_NO_MEMORY	Während des Vorgangs ist der CSP nicht mehr genügend Arbeitsspeicher vorhanden.

Bemerkungen

Die CryptVerifySignature Funktion schließt den Hash ab. Nach diesem Aufruf können dem Hash keine weiteren Daten hinzugefügt werden. Weitere Aufrufe von CryptHashData oder CryptHashSessionKey fehl. Nachdem die Anwendung mit dem Hash abgeschlossen wurde, sollte CryptDestroyHash aufgerufen werden, um das Hashobjekt zu zerstören.

Wenn Sie eine Signatur mithilfe der .NET Framework-APIs generieren und versuchen, sie mithilfe der CryptVerifySignature--Funktion zu überprüfen, schlägt die Funktion fehl, und GetLastError wird NTE_BAD_SIGNATUREzurückgegeben. Dies liegt an den unterschiedlichen Bytereihenfolgen zwischen der systemeigenen Win32-API und der .NET Framework-API.

Die systemeigene Kryptografie-API verwendet eine kleine endische Bytereihenfolge, während die .NET Framework-API big-endian byte order verwendet. Wenn Sie eine signatur überprüfen, die mit einer .NET Framework-API generiert wird, müssen Sie die Reihenfolge der Signaturbytes austauschen, bevor Sie die CryptVerifySignature--Funktion aufrufen, um die Signatur zu überprüfen.

Beispiele

Ein Beispiel, das die CryptVerifySignature--Funktion verwendet, finden Sie unter Beispiel-C-Programm: Signieren eines Hashs und Überprüfen der Hashsignatur.

Anmerkung

Der wincrypt.h-Header definiert CryptVerifySignature als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	wincrypt.h
Library	Advapi32.lib
DLL-	Advapi32.dll