Freigeben über


CryptSignHashA-Funktion (wincrypt.h)

Wichtig Diese API ist veraltet. Neue und vorhandene Software sollte mit der Verwendung von Kryptografie-APIs der nächsten Generation beginnen. Microsoft kann diese API in zukünftigen Versionen entfernen.
 
Die CryptSignHash-Funktion signiert Daten. Da alle Signaturalgorithmen asymmetrisch und daher langsam sind, lässt CryptoAPI nicht zu, dass Daten direkt signiert werden. Stattdessen werden zuerst Daten gehasht, und CryptSignHash wird verwendet, um den Hash zu signieren.

Syntax

BOOL CryptSignHashA(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwKeySpec,
  [in]      LPCSTR     szDescription,
  [in]      DWORD      dwFlags,
  [out]     BYTE       *pbSignature,
  [in, out] DWORD      *pdwSigLen
);

Parameter

[in] hHash

Handle des zu signierten Hashobjekts .

[in] dwKeySpec

Gibt den privaten Schlüssel an, der aus dem Container des Anbieters verwendet werden soll. Es kann AT_KEYEXCHANGE oder AT_SIGNATURE sein.

Der verwendete Signaturalgorithmus wird angegeben, wenn das Schlüsselpaar ursprünglich erstellt wird.

Der einzige Signaturalgorithmus, der vom Microsoft Base Cryptographic Provider unterstützt wird, ist der RSA Public Key-Algorithmus.

[in] szDescription

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

[in] dwFlags

Die folgenden Flagwerte werden definiert.

Wert Bedeutung
CRYPT_NOHASHOID
0x00000001
Wird mit RSA-Anbietern verwendet. Der Hashobjektbezeichner (Hash Object Identifier , OID) wird nicht in der Verschlüsselung mit öffentlichem RSA-Schlüssel platziert. Wenn dieses Flag nicht festgelegt ist, wird die Hash-OID in der Standardsignatur wie in der Definition von DigestInfo in PKCS #1 angegeben.
CRYPT_TYPE2_FORMAT
0x00000002
Dieses Flag wird nicht verwendet.
CRYPT_X931_FORMAT
0x00000004
Verwenden Sie die RSA-Signaturabstandsmethode, die im ANSI X9.31-Standard angegeben ist.

[out] pbSignature

Ein Zeiger auf einen Puffer, der die Signaturdaten empfängt.

Dieser Parameter kann NULL sein, um die Puffergröße für die Speicherbelegung festzulegen. Weitere Informationen finden Sie unter Abrufen von Daten mit unbekannter Länge.

[in, out] pdwSigLen

Ein Zeiger auf einen DWORD-Wert , der die Größe des pbSignature-Puffers in Bytes angibt. Wenn die Funktion zurückgibt, enthält der DWORD-Wert die Anzahl der im Puffer gespeicherten Bytes.

Hinweis Bei der Verarbeitung der im Puffer zurückgegebenen Daten müssen Anwendungen die tatsächliche Größe der zurückgegebenen Daten verwenden. Die tatsächliche Größe kann etwas kleiner als die Größe des bei der Eingabe angegebenen Puffers sein. (Bei der Eingabe werden Puffergrößen in der Regel groß genug angegeben, um sicherzustellen, dass die größtmöglichen Ausgabedaten in den Puffer passen.) Bei der Ausgabe wird die Variable aktualisiert, auf die dieser Parameter verweist, um die tatsächliche Größe der in den Puffer kopierten Daten widerzuspiegeln.
 

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion TRUE zurück.

Wenn die Funktion fehlschlägt, wird FALSE zurückgegeben. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Die von "NTE" vorangestellten Fehlercodes werden von dem jeweiligen CSP generiert, den Sie verwenden. Es folgen einige mögliche Fehlercodes.

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 in den meisten Fällen ein ungültiger Zeiger.
ERROR_MORE_DATA
Der vom pbSignature-Parameter angegebene Puffer ist nicht groß genug, um die zurückgegebenen Daten zu enthalten. Die erforderliche Puffergröße in Bytes befindet sich im DWORD-WertpdwSigLen.
NTE_BAD_ALGID
Das hHash-Handle gibt einen Algorithmus an, den dieser CSP nicht unterstützt, oder der dwKeySpec-Parameter hat einen falschen Wert.
NTE_BAD_FLAGS
Der dwFlags-Parameter ist ungleich null.
NTE_BAD_HASH
Das vom hHash-Parameter angegebene Hashobjekt ist ungültig.
NTE_BAD_UID
Der CSP-Kontext, der beim Erstellen des Hashobjekts angegeben wurde, kann nicht gefunden werden.
NTE_NO_KEY
Der von dwKeySpec angegebene private Schlüssel ist nicht vorhanden.
NTE_NO_MEMORY
Während des Vorgangs war für den CSP der Arbeitsspeicher nicht mehr vorhanden.

Hinweise

Vor dem Aufrufen dieser Funktion muss die CryptCreateHash-Funktion aufgerufen werden, um ein Handle für ein Hashobjekt abzurufen. Die Funktion CryptHashData oder CryptHashSessionKey wird dann verwendet, um die Daten- oder Sitzungsschlüssel dem Hashobjekt hinzuzufügen. Die CryptSignHash-Funktion schließt den Hash ab.

Während der DSS-CSP hashing sowohl mit dem MD5- als auch mit den SHA-Hashalgorithmen unterstützt, unterstützt der DSS-CSP nur das Signieren von SHA-Hashes.

Nachdem diese Funktion aufgerufen wurde, können dem Hash keine weiteren Daten hinzugefügt werden. Zusätzliche Aufrufe von CryptHashData oder CryptHashSessionKey schlagen fehl.

Nachdem die Anwendung die Verwendung des Hashs abgeschlossen hat, zerstören Sie das Hashobjekt, indem Sie die CryptDestroyHash-Funktion aufrufen.

Standardmäßig verwenden die Microsoft RSA-Anbieter die PKCS #1-Auffüllungsmethode für die Signatur. Die Hash-OID im DigestInfo-Element der Signatur wird automatisch auf die Algorithmus-OID festgelegt, die dem Hashobjekt zugeordnet ist. Wenn Sie das CRYPT_NOHASHOID-Flag verwenden, wird diese OID in der Signatur weggelassen.

Gelegentlich muss ein Hashwert, der an anderer Stelle generiert wurde, signiert werden. Dies kann mithilfe der folgenden Abfolge von Vorgängen erfolgen:

  1. Erstellen Sie mithilfe von CryptCreateHash ein Hashobjekt.
  2. Legen Sie den Hashwert im Hashobjekt mithilfe des HP_HASHVAL Werts des dwParam-Parameters in CryptSetHashParam fest.
  3. Signieren Sie den Hashwert mithilfe von CryptSignHash , und rufen Sie einen digitalen Signaturblock ab.
  4. Zerstören Sie das Hashobjekt mithilfe von CryptDestroyHash.

Beispiele

Das folgende Beispiel zeigt das Signieren von Daten, indem zuerst die zu signierenden Daten gehasht und dann der Hash mit der CryptSignHash-Funktion signiert wird.

//-------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV hProv;
BYTE *pbBuffer= (BYTE *)"Sample data that is to be signed.";
DWORD dwBufferLen = strlen((char *)pbBuffer)+1;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// This code assumes that a cryptographic context handle, hProv,
// and a hash handle, hHash, are available.
// For code needed to acquire the context, see "Example C Program: 
// Signing a Hash and Verifying the Hash Signature."

//--------------------------------------------------------------------
// Compute the cryptographic hash of the buffer.

if(CryptHashData(
   hHash, 
   pbBuffer, 
   dwBufferLen, 
   0)) 
{
     printf("The data buffer has been hashed.\n");
}
else
{
     printf("Error during CryptHashData.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Determine the size of the signature and allocate memory.

dwSigLen= 0;
if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   NULL, 
   &dwSigLen)) 
{
     printf("Signature length %d found.\n",dwSigLen);
}
else
{
     printf("Error during CryptSignHash\n");
     exit(1);
}
//--------------------------------------------------------------------
// Allocate memory for the signature buffer.

if(pbSignature = (BYTE *)malloc(dwSigLen))
{
     printf("Memory allocated for the signature.\n");
}
else
{
     printf("Out of memory\n");
     exit(1);
}
//--------------------------------------------------------------------
// Sign the hash object.

if(CryptSignHash(
   hHash, 
   AT_SIGNATURE, 
   szDescription, 
   0, 
   pbSignature, 
   &dwSigLen)) 
{
     printf("pbSignature is the hash signature.\n");
}
else
{
     printf("Error during CryptSignHash.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Destroy the hash object.

if(hHash) 
  CryptDestroyHash(hHash);

Ein vollständiges Beispiel einschließlich des Kontexts für diesen Code finden Sie unter Beispiel-C-Programm: Signieren eines Hashs und Überprüfen der Hashsignatur.

Hinweis

Der wincrypt.h-Header definiert CryptSignHash 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
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile wincrypt.h
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

Hash- und digitale Signaturfunktionen