Funzione CryptGenRandom (wincrypt.h)

Articolo
08/27/2023

Importante Questa API è deprecata. Il software nuovo ed esistente deve iniziare a usare le API cryptography next generation. Microsoft potrebbe rimuovere questa API nelle versioni future.

La funzione CryptGenRandom riempie un buffer con byte casuali crittograficamente.

Sintassi

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

Parametri

[in] hProv

Handle di un provider di servizi di crittografia (CSP) creato da una chiamata a CryptAcquireContext.

[in] dwLen

Numero di byte di dati casuali da generare.

[in, out] pbBuffer

Buffer per ricevere i dati restituiti. Questo buffer deve avere una lunghezza minima di dwLen .

Facoltativamente, l'applicazione può riempire questo buffer con dati da usare come valore di inizializzazione casuale ausiliario.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero (TRUE).

Se la funzione ha esito negativo, il valore restituito è zero (FALSE). Per informazioni sugli errori estesi, chiamare GetLastError.

I codici di errore preceduti da "NTE" vengono generati dal CSP specifico usato. Nella tabella seguente sono elencati alcuni codici di errore possibili.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Uno dei parametri specifica un handle non valido.
ERROR_INVALID_PARAMETER	Uno dei parametri contiene un valore non valido. Si tratta più spesso di un puntatore che non è valido.
NTE_BAD_UID	Il parametro hProv non contiene un handle di contesto valido.
NTE_FAIL	La funzione non è riuscita in modo imprevisto.

Commenti

I dati prodotti da questa funzione sono crittograficamente casuali. È molto più casuale dei dati generati dal tipico generatore di numeri casuali, ad esempio quello fornito con il compilatore C.

Questa funzione viene spesso usata per generare vettori di inizializzazione casuali e valori salt.

I generatori di numeri casuali software funzionano fondamentalmente allo stesso modo. Iniziano con un numero casuale, noto come valore di inizializzazione, e quindi usano un algoritmo per generare una sequenza pseudo-casuale di bit basata su di essa. La parte più difficile di questo processo è ottenere un seme che è veramente casuale. In genere si basa sulla latenza di input dell'utente o sull'instabilità da uno o più componenti hardware.

Con i provider di servizi di configurazione Microsoft , CryptGenRandom usa lo stesso generatore di numeri casuali usato da altri componenti di sicurezza. Ciò consente a numerosi processi di contribuire a un seeding a livello di sistema. CryptoAPI archivia un valore di inizializzazione casuale intermedio con ogni utente. Per formare il valore di inizializzazione per il generatore di numeri casuali, un'applicazione chiamante fornisce bit che potrebbero avere, ad esempio l'input di tempo del mouse o della tastiera, che vengono quindi combinati con il valore di inizializzazione archiviato e i vari dati di sistema e i dati utente, ad esempio l'ID processo e l'ID del thread, l'orologio di sistema, l'ora di sistema, il contatore di sistema, stato della memoria, cluster di dischi liberi, blocco di ambiente utente con hash. Questo risultato viene usato per inizializzare il generatore di numeri pseudorandomi (PRNG). In Windows Vista con Service Pack 1 (SP1) e versioni successive viene usata un'implementazione del prNG basato sulla modalità contatore AES specificata nella pubblicazione speciale NIST 800-90. In Windows Vista, Windows Storage Server 2003 e Windows XP, viene usato il PRNG specificato in FIPS (Federal Information Processing Standard) 186-2. Se un'applicazione ha accesso a una buona origine casuale, può riempire il buffer pbBuffer con alcuni dati casuali prima di chiamare CryptGenRandom. Il provider di servizi di configurazione usa quindi questi dati per casualizzare ulteriormente il valore di inizializzazione interno. È accettabile omettere il passaggio di inizializzazione del buffer pbBuffer prima di chiamare CryptGenRandom.

Esempio

Nell'esempio seguente viene illustrata la generazione di 8 byte casuali. Possono essere usati per creare chiavi crittografiche o per qualsiasi applicazione che usa numeri casuali. Per un esempio che include il contesto completo per questo esempio, vedere Esempio di programma C: duplicazione di una chiave di sessione.

//--------------------------------------------------------------------
// 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);
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincrypt.h
Libreria	Advapi32.lib
DLL	Advapi32.dll