Funzione BCryptGenRandom (bcrypt.h)

Articolo
07/16/2024

La funzione BCryptGenRandom genera un numero casuale.

Sintassi

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

Parametri

[in, out] hAlgorithm

Handle di un provider di algoritmi creato usando la funzione BCryptOpenAlgorithmProvider. L'algoritmo specificato al momento della creazione del provider deve supportare l'interfaccia del generatore di numeri casuali.

[in, out] pbBuffer

Indirizzo di un buffer che riceve il numero casuale. Le dimensioni di questo buffer vengono specificate dal parametro cbBuffer .

[in] cbBuffer

Dimensione, in byte, del buffer pbBuffer .

[in] dwFlags

Set di flag che modificano il comportamento di questa funzione. Questo parametro può essere zero o il valore seguente.

Valore	Significato
BCRYPT_RNG_USE_ENTROPY_IN_BUFFER 0x00000001	Questa funzione userà il numero nel buffer pbBuffer come entropia aggiuntiva per il numero casuale. Se questo flag non viene specificato, questa funzione userà un numero casuale per l'entropia. Windows 8 e versioni successive: Questo flag viene ignorato in Windows 8 e versioni successive.
BCRYPT_USE_SYSTEM_PREFERRED_RNG 0x00000002	Usare l'algoritmo generatore di numeri casuali preferito dal sistema. Il parametro hAlgorithm deve essere NULL. BCRYPT_USE_SYSTEM_PREFERRED_RNG è supportato solo in PASSIVE_LEVELIRQL. Per altre informazioni, vedere Osservazioni. Windows Vista: Questo flag non è supportato senza SP2.

Valore restituito

Restituisce un codice di stato che indica l'esito positivo o negativo della funzione.

I codici restituiti possibili includono, ma non solo, quanto segue.

Codice restituito	Descrizione
STATUS_SUCCESS	La funzione ha avuto esito positivo.
STATUS_INVALID_HANDLE	L'handle nel parametro hAlgorithm non è valido.
STATUS_INVALID_PARAMETER	Uno o più parametri non sono validi.

Osservazioni

Il provider di numeri casuali predefinito implementa un algoritmo per la generazione di numeri casuali conformi allo standard NIST SP800-90, in particolare la parte CTR_DRBG di tale standard.

Windows Vista: prima di Windows Vista con Service Pack 1 (SP1) il provider di numeri casuali predefinito implementa un algoritmo per la generazione di numeri casuali conformi allo standard FIPS 186-2.

A seconda delle modalità del processore supportate da un provider, è possibile chiamare BCryptGenRandom dalla modalità utente o dal kernel. I chiamanti in modalità kernel possono essere eseguiti in PASSIVE_LEVELirQL o DISPATCH_LEVEL IRQL. Se il livello IRQL corrente è DISPATCH_LEVEL, l'handle fornito nella parametro hAlgorithm deve essere stato aperto usando il flag di BCRYPT_PROV_DISPATCH e qualsiasi puntatore passato alla funzione BCryptGenRandom deve fare riferimento alla memoria non di pagina (o bloccata).Windows Vista: Il provider Microsoft non supporta la chiamata a DISPATCH_LEVEL.

Per chiamare questa funzione in modalità kernel, usare Cng.lib, che fa parte del Driver Development Kit (DDK). Windows Server 2008 e Windows Vista: Per chiamare questa funzione in modalità kernel, usare Ksecdd.lib.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	bcrypt.h
libreria	Bcrypt.lib o Cng.lib(per la modalità kernel)
dll	Bcrypt.dll

Condividi tramite