CryptCreateHash-Funktion (wincrypt.h)

Artikel
08/27/2023

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 CryptCreateHash-Funktion initiiert das Hashing eines Datenstroms. Es erstellt ein Handle für ein CSP-Hashobjekt (Cryptographic Service Provider) und gibt es an die aufrufende Anwendung zurück. Dieses Handle wird in nachfolgenden Aufrufen von CryptHashData und CryptHashSessionKey verwendet, um Sitzungsschlüssel und andere Datenströme zu hashen.

Syntax

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Parameter

[in] hProv

Ein Handle für einen CSP, der durch einen Aufruf von CryptAcquireContext erstellt wurde.

[in] Algid

Ein ALG_ID Wert, der den zu verwendenden Hashalgorithmus identifiziert.

Die gültigen Werte für diesen Parameter variieren je nach verwendetem CSP. Eine Liste der Standardalgorithmen finden Sie unter Hinweise.

[in] hKey

Wenn der Typ des Hashalgorithmus ein schlüsselbasierter Hash ist, z. B . der HMAC-Algorithmus (Hash-Based Message Authentication Code ) oder der MAC-Algorithmus ( Message Authentication Code ), wird der Schlüssel für den Hash in diesem Parameter übergeben. Bei Nichtschlüsselalgorithmen muss dieser Parameter auf 0 (null) festgelegt werden.

Bei Schlüsselalgorithmen muss der Schlüssel einem Blockverschlüsselungsschlüssel wie RC2 entsprechen, der über einen Verschlüsselungsmodus der Verschlüsselungsblockverkettung (Cipher Block Chaining , CBC) verfügt.

[in] dwFlags

Der folgende Flagwert wird definiert.

Wert	Bedeutung
CRYPT_SECRETDIGEST 0x00000001	Dieses Flag wird nicht verwendet.

[out] phHash

Die Adresse, in die die Funktion ein Handle in das neue Hashobjekt kopiert. Wenn Sie die Verwendung des Hashobjekts abgeschlossen haben, lassen Sie das Handle los, indem Sie die CryptDestroyHash-Funktion aufrufen.

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. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.

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_NOT_ENOUGH_MEMORY	Beim Betriebssystem ist während des Vorgangs nicht mehr genügend Arbeitsspeicher vorhanden.
NTE_BAD_ALGID	Der Algid-Parameter gibt einen Algorithmus an, den dieser CSP nicht unterstützt.
NTE_BAD_FLAGS	Der dwFlags-Parameter ist ungleich null.
NTE_BAD_KEY	Ein schlüsselierter Hashalgorithmus , z. B. CALG_MAC, wird von Algid angegeben, und der hKey-Parameter ist entweder null oder gibt ein ungültiges Schlüsselhandle an. Dieser Fehlercode wird auch zurückgegeben, wenn der Schlüssel für eine Streamchiffre verwendet wird oder wenn der Verschlüsselungsmodus ein anderer als CBC ist.
NTE_NO_MEMORY	Während des Vorgangs war für den CSP der Arbeitsspeicher nicht mehr vorhanden.

Hinweise

Eine Liste der Microsoft-Dienstanbieter und der von ihnen implementierten Algorithmen finden Sie unter Microsoft Cryptographic Service Providers.

Die Berechnung des tatsächlichen Hash erfolgt mit den Funktionen CryptHashData und CryptHashSessionKey . Diese erfordern ein Handle für das Hashobjekt. Nachdem alle Daten dem Hashobjekt hinzugefügt wurden, kann jeder der folgenden Vorgänge ausgeführt werden:

Der Hashwert kann mithilfe von CryptGetHashParam abgerufen werden.
Ein Sitzungsschlüssel kann mithilfe von CryptDeriveKey abgeleitet werden.
Der Hash kann mit CryptSignHash signiert werden.
Eine Signatur kann mithilfe von CryptVerifySignature überprüft werden.

Nachdem eine der Funktionen aus dieser Liste aufgerufen wurde, können CryptHashData und CryptHashSessionKey nicht mehr aufgerufen werden.

Beispiele

Das folgende Beispiel zeigt das Initiieren des Hashings eines Datenstroms. Es erstellt ein Handle für ein Hashobjekt und gibt es an die aufrufende Anwendung zurück. Dieses Handle wird in nachfolgenden Aufrufen von CryptHashData und CryptHashSessionKey verwendet, um jeden Datenstrom zu hashen. Ein Beispiel, das den vollständigen Kontext für dieses Beispiel enthält, finden Sie unter Beispiel-C-Programm: Erstellen und Hashing eines Sitzungsschlüssels. Ein weiteres Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Signieren eines Hashs und Überprüfen der Hashsignatur.

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

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