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.
| Wert | Bedeutung |
|---|---|
|
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. |
|
Dieses Flag wird nicht verwendet. |
|
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.
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 |
|---|---|
|
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 ungültiger Zeiger. |
|
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. |
|
Das hHash-Handle gibt einen Algorithmus an, den dieser CSP nicht unterstützt, oder der dwKeySpec-Parameter hat einen falschen Wert. |
|
Der dwFlags-Parameter ist ungleich null. |
|
Das vom 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 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:
- 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 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 |