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 Hashobjekts, signiert werden sollen.
[in] dwKeySpec
Gibt den privaten Schlüssel an, der vom Container des Anbieters verwendet werden soll. Es kann AT_KEYEXCHANGE oder AT_SIGNATURE werden.
Der verwendete Signaturalgorithmus wird angegeben, wenn das Schlüsselpaar ursprünglich erstellt wurde.
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-Kryptografieanbieter unterstützt.
[in] dwFlags
Die folgenden Flagwerte werden definiert.
| Wert | Bedeutung |
|---|---|
|
Wird bei RSA-Anbietern verwendet. Der Hash-Objektbezeichner (OID) wird nicht in die RSA Public Key-Verschlüsselung eingefügt. Wenn dieses Flag nicht festgelegt ist, wird das Hash-OID in der Standardsignatur wie in der Definition von DigestInfo in PKCS #1 angegeben. |
|
Dieses Kennzeichen 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 Speicherzuweisungszwecke 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 Byte angibt. Wenn die Funktion zurückgegeben wird, enthält der DWORD- Wert die Anzahl der im Puffer gespeicherten Bytes.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion TRUEzurück.
Wenn die Funktion fehlschlägt, wird FALSE-zurückgegeben. 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 |
|---|---|
|
Einer der Parameter gibt ein ungültiges Handle an. |
|
Einer der Parameter enthält einen ungültigen Wert. Dies ist am häufigsten ein ungültiger Zeiger. |
|
Der vom pbSignature Parameter angegebene Puffer ist nicht groß genug, um die zurückgegebenen Daten aufzunehmen. Die erforderliche Puffergröße in Byte befindet sich im wert pdwSigLenDWORD-. |
|
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 nonzero. |
|
Das vom hHash Parameter angegebene Hashobjekt ist ungültig. |
|
Der CSP-Kontext, der beim Erstellen des Hashobjekts angegeben wurde, kann nicht gefunden werden. |
|
Der durch dwKeySpec- angegebene private Schlüssel ist nicht vorhanden. |
|
Während des Vorgangs ist der CSP nicht mehr genügend Arbeitsspeicher vorhanden. |
Bemerkungen
Vor dem Aufrufen dieser Funktion muss die CryptCreateHash--Funktion aufgerufen werden, um ein Handle zu einem Hashobjekt abzurufen. Die CryptHashData oder CryptHashSessionKey--Funktion wird dann verwendet, um dem Hashobjekt die Daten oder Sitzungsschlüssel hinzuzufügen. Die CryptSignHash--Funktion schließt den Hash ab.
Während der DSS-CSP Hashing sowohl mit den MD5- als auch 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. Weitere Aufrufe von CryptHashData oder CryptHashSessionKey fehl.
Nachdem die Anwendung den Hash verwendet hat, zerstören Sie das Hashobjekt, indem Sie die CryptDestroyHash--Funktion aufrufen.
Standardmäßig verwenden die Microsoft RSA-Anbieter die PKCS #1 Padding-Methode für die Signatur. Das Hash-OID im DigestInfo Element der Signatur wird automatisch auf den Algorithmus OID festgelegt, der dem Hashobjekt zugeordnet ist. Wenn Sie das CRYPT_NOHASHOID-Flag verwenden, wird dieses OID aus der Signatur weggelassen.
Gelegentlich muss ein Hashwert, der an anderer Stelle generiert wurde, signiert werden. Dies kann mithilfe der folgenden Sequenz von Vorgängen erfolgen:
- Erstellen Sie ein Hashobjekt mithilfe CryptCreateHash.
- Legen Sie den Hashwert im Hashobjekt mithilfe des HP_HASHVAL Werts des dwParam--Parameters in CryptSetHashParamfest.
- Signieren Sie den Hashwert mithilfe CryptSignHash und rufen Sie einen digitalen Signaturblock ab.
- Zerstören Sie das Hashobjekt mithilfe CryptDestroyHash.
Beispiele
Das folgende Beispiel zeigt das Signieren von Daten, indem zuerst das signierte Datenhashing und anschließend das Signieren des Hash mithilfe der CryptSignHash--Funktion erfolgt.
//-------------------------------------------------------------
// 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.
Anmerkung
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 |
|---|---|
| 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 |