BCryptGenRandom-Funktion (bcrypt.h)

  • Artikel

Die Funktion BCryptGenRandom generiert eine Zufallszahl.

Syntax

NTSTATUS BCryptGenRandom(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [in, out] PUCHAR            pbBuffer,
  [in]      ULONG             cbBuffer,
  [in]      ULONG             dwFlags
);

Parameter

[in, out] hAlgorithm

Das Handle eines Algorithmusanbieters, der mit der Funktion BCryptOpenAlgorithmProvider erstellt wurde. Der Algorithmus, der bei der Erstellung des Anbieters angegeben wurde, muss die Schnittstelle für den Zufallszahlengenerator unterstützen.

[in, out] pbBuffer

Die Adresse eines Puffers, der die Zufallszahl empfängt. Die Größe dieses Puffers wird durch den cbBuffer-Parameter angegeben.

[in] cbBuffer

Die Größe des pbBuffer-Puffers in Bytes.

[in] dwFlags

Ein Satz von Flags, die das Verhalten dieser Funktion ändern. Dieser Parameter kann null oder der folgende Wert sein.

Wert Bedeutung
BCRYPT_RNG_USE_ENTROPY_IN_BUFFER
0x00000001
 Diese Funktion verwendet die Zahl im pbBuffer-Puffer als zusätzliche Entropie für die Zufallszahl. Wenn dieses Flag nicht angegeben ist, verwendet diese Funktion eine Zufallszahl für die Entropie.

Windows 8 und höher: Dieses Flag wird in Windows 8 und höher ignoriert.
BCRYPT_USE_SYSTEM_PREFERRED_RNG
0x00000002
 Verwenden Sie den vom System bevorzugten Zufallszahlengeneratoralgorithmus. Der hAlgorithm-Parameter muss NULL sein.

BCRYPT_USE_SYSTEM_PREFERRED_RNG wird nur in PASSIVE_LEVELIRQL unterstützt. Weitere Informationen finden Sie in den Hinweisen.

Windows Vista: Dieses Flag wird ohne SP2 nicht unterstützt.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode Beschreibung
STATUS_SUCCESS
 Die Funktion war erfolgreich.
STATUS_INVALID_HANDLE
 Das Handle im hAlgorithm-Parameter ist ungültig.
STATUS_INVALID_PARAMETER
 Mindestens ein Parameter ist ungültig.

Hinweise

Der Standardanbieter für Zufallszahlen implementiert einen Algorithmus zum Generieren von Zufallszahlen, der dem NIST SP800-90-Standard entspricht, insbesondere dem CTR_DRBG Teil dieses Standards.

Windows Vista: Vor Windows Vista mit Service Pack 1 (SP1) implementiert der Standardanbieter für Zufallszahlen einen Algorithmus zum Generieren von Zufallszahlen, der dem FIPS 186-2-Standard entspricht.

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptGenRandom entweder aus dem Benutzermodus oder dem Kernelmodus aufgerufen werden. Aufrufer im Kernelmodus können entweder am PASSIVE_LEVELIRQL oder DISPATCH_LEVEL IRQL ausgeführt werden. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEL ist, muss das im hAlgorithm-Parameter bereitgestellte Handle mit dem flag BCRYPT_PROV_DISPATCH geöffnet worden sein, und alle an die BCryptGenRandom-Funktion übergebenen Zeiger müssen auf nicht ausgestellten (oder gesperrten) Speicher verweisen. Windows Vista: Der Microsoft-Anbieter unterstützt keine Aufrufe unter DISPATCH_LEVEL.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, die Teil des Driver Development Kit (DDK) ist. Windows Server 2008 und Windows Vista: Verwenden Sie Ksecdd.lib, um diese Funktion im Kernelmodus aufzurufen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile bcrypt.h
Bibliothek Bcrypt.lib oder Cng.lib(Für Kernelmodus)
DLL Bcrypt.dll