BCryptGenRandom-Funktion (bcrypt.h)

Artikel
11/20/2024

Die BCryptGenRandom Funktion 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 mithilfe der BCryptOpenAlgorithmProvider-Funktion erstellt wurde. Der Algorithmus, der beim Erstellen des Anbieters angegeben wurde, muss die Zufallszahlengeneratorschnittstelle 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 Byte.

[in] dwFlags

Eine Reihe 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 Kennzeichen nicht angegeben ist, verwendet diese Funktion eine Zufallszahl für die Entropie. Windows 8 und höher: Dieses Kennzeichen 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 bei PASSIVE_LEVELIRQL-unterstützt. Weitere Informationen finden Sie in den Hinweisen. Windows Vista: Dieses Flag wird ohne SP2 nicht unterstützt.

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 Kennzeichen nicht angegeben ist, verwendet diese Funktion eine Zufallszahl für die Entropie.

Windows 8 und höher: Dieses Kennzeichen 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 bei 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 Statuscode zurück, der den Erfolg oder Fehler der Funktion angibt.

Mögliche Rückgabecodes umfassen, aber nicht beschränkt auf Folgendes.

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.

Bemerkungen

Der Standardmäßige Zufallszahlenanbieter implementiert einen Algorithmus zum Generieren von Zufallszahlen, der dem NIST SP800-90-Standard entspricht, insbesondere den CTR_DRBG Teil dieses Standards.

Windows Vista: Vor Windows Vista mit Service Pack 1 (SP1) implementiert der Standardmäßige Zufallszahlenanbieter einen Algorithmus zum Generieren von Zufallszahlen, die dem FIPS 186-2-Standard entsprechen.

Je nachdem, welche Prozessormodi ein Anbieter unterstützt, kann BCryptGenRandom entweder über den Benutzermodus oder den Kernelmodus aufgerufen werden. Kernelmodusaufrufer können entweder PASSIVE_LEVELIRQL- oder DISPATCH_LEVEL IRQL ausgeführt werden. Wenn die aktuelle IRQL-Ebene DISPATCH_LEVEList, muss das im hAlgorithm Parameter bereitgestellte Handle mithilfe des BCRYPT_PROV_DISPATCH-Flags geöffnet worden sein, und alle Zeiger, die an die BCryptGenRandom--Funktion übergeben werden, müssen auf nicht seitenseitigen (oder gesperrten) Speicher verweisen. Windows Vista: Der Microsoft-Anbieter unterstützt keine Anrufe unter DISPATCH_LEVEL.

Um diese Funktion im Kernelmodus aufzurufen, verwenden Sie Cng.lib, das 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
mindestens unterstützte Client-	Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	bcrypt.h
Library	Bcrypt.lib oder Cng.lib(Für Kernelmodus)
DLL-	Bcrypt.dll

Freigeben über