CryptSignHashA-Funktion (wincrypt.h)

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.

[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.

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.

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.

Anforderungen

Weitere Informationen

CryptCreateHash

CryptDestroyHash

CryptHashData

CryptHashSessionKey

CryptVerifySignature

Hash- und digitale Signaturfunktionen