CryptSignHashW-Funktion (wincrypt.h)
Syntax
BOOL CryptSignHashW(
[in] HCRYPTHASH hHash,
[in] DWORD dwKeySpec,
[in] LPCWSTR 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, den der Microsoft Base Cryptographic Provider unterstützt, 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 Base Cryptographic Provider unterstützt.
[in] dwFlags
Die folgenden Flagwerte werden definiert.
| Wert | Bedeutung |
|---|---|
|
Wird mit RSA-Anbietern verwendet. Der Hashobjektbezeichner (Hash Object Identifier , OID) wird nicht in der Verschlüsselung des öffentlichen RSA-Schlüssels platziert. Wenn dieses Flag nicht festgelegt ist, entspricht die Hash-OID in der Standardsignatur der Definition von DigestInfo in PKCS #1. |
|
Dieses Flag wird nicht verwendet. |
|
Verwenden Sie die RSA-Signaturfüllungsmethode, 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 Speicherbelegungszwecke festzulegen. Weitere Informationen finden Sie unter Abrufen von Daten 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, gibt sie FALSE zurück. 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 |
|---|---|
|
Einer der Parameter gibt ein ungültiges Handle an. |
|
Einer der Parameter enthält einen ungültigen Wert. Dies ist in den meisten Fällen ein nicht gültiger Zeiger. |
|
Der vom pbSignature-Parameter angegebene Puffer ist nicht groß genug, um die zurückgegebenen Daten aufzunehmen. Die erforderliche Puffergröße in Bytes entspricht dem DWORD-Wert pdwSigLen. |
|
Das hHash-Handle gibt einen Algorithmus an, den dieser CSP nicht unterstützt, oder der dwKeySpec-Parameter weist einen falschen Wert auf. |
|
Der dwFlags-Parameter ist nonzero. |
|
Das durch den hHash-Parameter angegebene Hashobjekt ist ungültig. |
|
Der CSP-Kontext, der beim Erstellen des Hashobjekts angegeben wurde, kann nicht gefunden werden. |
|
Der von dwKeySpec angegebene private Schlüssel ist nicht vorhanden. |
|
Während des Vorgangs ging dem CSP der Arbeitsspeicher aus. |
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 zum Hashobjekt hinzuzufügen. Die CryptSignHash-Funktion schließt den Hash ab.
Während der DSS-CSP das 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 Funktion CryptDestroyHash 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. Die Verwendung des CRYPT_NOHASHOID-Flags führt dazu, dass diese OID in der Signatur weggelassen wird.
Gelegentlich muss ein an anderer Stelle generierter Hashwert signiert werden. Dies kann mithilfe der folgenden Vorgangssequenz erfolgen:
- Erstellen Sie mithilfe von CryptCreateHash ein Hashobjekt.
- Legen Sie den Hashwert im Hashobjekt mithilfe des HP_HASHVAL Werts des dwParam-Parameters in CryptSetHashParam fest.
- Signieren Sie den Hashwert mithilfe von CryptSignHash , und rufen Sie einen digitalen Signaturblock ab.
- Zerstören Sie das Hashobjekt mithilfe von CryptDestroyHash.
Beispiele
Das folgende Beispiel zeigt das Signieren von Daten, indem zuerst die zu signierenden Daten und dann der Hash mithilfe der CryptSignHash-Funktion signiert werden.
//-------------------------------------------------------------
// 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 nicht codierungsneutralem Code 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 |