CryptGenRandom-Funktion (wincrypt.h)

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 CryptGenRandom-Funktion füllt einen Puffer mit kryptografisch zufälligen Bytes aus.

Syntax

BOOL CryptGenRandom(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwLen,
  [in, out] BYTE       *pbBuffer
);

Parameter

[in] hProv

Handle eines Kryptografiedienstanbieters (CSP ), der durch einen Aufruf von CryptAcquireContext erstellt wurde.

[in] dwLen

Anzahl der Bytes der zu generierenden Zufallsdaten.

[in, out] pbBuffer

Puffer zum Empfangen der zurückgegebenen Daten. Dieser Puffer muss mindestens dwLen-Bytes lang sein.

Optional kann die Anwendung diesen Puffer mit Daten füllen, die als zufälliger Hilfswert verwendet werden können.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich null (TRUE).

Wenn die Funktion fehlschlägt, ist der Rückgabewert 0 (FALSE). Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.

Die von "NTE" vorangestellten Fehlercodes werden von dem jeweiligen verwendeten CSP generiert. Einige mögliche Fehlercodes sind in der folgenden Tabelle 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.
NTE_BAD_UID	Der hProv-Parameter enthält kein gültiges Kontexthandle.
NTE_FAIL	Die Funktion ist auf unerwartete Weise fehlgeschlagen.

Hinweise

Die von dieser Funktion erzeugten Daten sind kryptografisch zufällig. Es ist weitaus zufälliger als die Daten, die vom typischen Zufallszahlengenerator generiert werden, z. B. dem, der mit Ihrem C-Compiler geliefert wird.

Diese Funktion wird häufig verwendet, um zufällige Initialisierungsvektoren und Salzwerte zu generieren.

Software-Zufallszahlengeneratoren funktionieren grundsätzlich genauso. Sie beginnen mit einer Zufallszahl, die als Seed bezeichnet wird, und verwenden dann einen Algorithmus, um eine pseudo-zufällige Sequenz von Bits basierend darauf zu generieren. Der schwierigste Teil dieses Prozesses ist es, einen Seed zu erhalten, der wirklich zufällig ist. Dies basiert in der Regel auf der Latenz von Benutzereingaben oder dem Jitter durch eine oder mehrere Hardwarekomponenten.

Bei Microsoft-CSPs verwendet CryptGenRandom den gleichen Zufallszahlengenerator, der auch von anderen Sicherheitskomponenten verwendet wird. Dadurch können zahlreiche Prozesse zu einem systemweiten Seed beitragen. CryptoAPI speichert einen zufälligen Zwischenwert mit jedem Benutzer. Um den Ausgangswert für den Zufallszahlengenerator zu bilden, stellt eine aufrufende Anwendung Bits bereit, die für instance, Maus- oder Tastatur-Timing-Eingaben vorhanden sein könnten, die dann sowohl mit dem gespeicherten Startwert als auch mit verschiedenen Systemdaten und Benutzerdaten wie prozess-ID und Thread-ID, der Systemuhr, der Systemzeit, dem Systemzähler kombiniert werden. Arbeitsspeicher status, kostenlose Datenträgercluster, der Hashbenutzerumgebungsblock. Dieses Ergebnis wird verwendet, um den Pseudorandomzahlengenerator (PRNG) zu seeden. In Windows Vista mit Service Pack 1 (SP1) und höher wird eine Implementierung der in der NIST-Sonderveröffentlichung 800-90 angegebenen AES-Zählermodus-basierten PRNG verwendet. In Windows Vista, Windows Storage Server 2003 und Windows XP wird die in Federal Information Processing Standard (FIPS) 186-2 angegebene PRNG verwendet. Wenn eine Anwendung Zugriff auf eine gute zufallsbasierte Quelle hat, kann sie den pbBuffer-Puffer vor dem Aufruf von CryptGenRandom mit zufallsbasierten Daten füllen. Der CSP verwendet diese Daten dann, um seinen internen Seed weiter zufällig zu erstellen. Es ist akzeptabel, den Schritt der Initialisierung des pbBuffer-Puffers auszulassen, bevor CryptGenRandom aufgerufen wird.

Beispiele

Das folgende Beispiel zeigt die Generierung von 8 zufälligen Bytes. Diese können verwendet werden, um kryptografische Schlüssel zu erstellen oder für jede Anwendung, die Zufallszahlen verwendet. Ein Beispiel, das den vollständigen Kontext für dieses Beispiel enthält, finden Sie unter Beispiel-C-Programm: Duplizieren eines Sitzungsschlüssels.

//--------------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV   hCryptProv;
BYTE         pbData[16];

//--------------------------------------------------------------------
//  This code assumes that a cryptographic context has been acquired 
//  For code details, see "Example C Program: Duplicating a Session 
//  Key."

//--------------------------------------------------------------------
// Generate a random initialization vector.

if(CryptGenRandom(
   hCryptProv, 
   8, 
   pbData)) 
{
     printf("Random sequence generated. \n");
}
else
{
     printf("Error during CryptGenRandom.\n");
     exit(1);
}

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

Weitere Informationen

CryptAcquireContext

CryptGenKey

CryptSetKeyParam

Schlüsselgenerierung und Exchange-Funktionen