Fonction CryptGenRandom (wincrypt.h)

Article
08/27/2023

Important Cette API est déconseillée. Les logiciels nouveaux et existants doivent commencer à utiliser les API de nouvelle génération de chiffrement. Microsoft peut supprimer cette API dans les versions ultérieures.

La fonction CryptGenRandom remplit une mémoire tampon avec des octets aléatoires de chiffrement.

Syntaxe

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

Paramètres

[in] hProv

Handle d’un fournisseur de services de chiffrement (CSP) créé par un appel à CryptAcquireContext.

[in] dwLen

Nombre d’octets de données aléatoires à générer.

[in, out] pbBuffer

Mémoire tampon pour recevoir les données retournées. Cette mémoire tampon doit avoir au moins une longueur dwLen octets.

Si vous le souhaitez, l’application peut remplir cette mémoire tampon avec des données à utiliser comme amorçage aléatoire auxiliaire.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).

Si la fonction échoue, la valeur de retour est zéro (FALSE). Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Les codes d’erreur préfacés par « NTE » sont générés par le fournisseur de solutions cloud en cours d’utilisation. Certains codes d’erreur possibles sont répertoriés dans le tableau suivant.

Code de retour	Description
ERROR_INVALID_HANDLE	L’un des paramètres spécifie un handle qui n’est pas valide.
ERROR_INVALID_PARAMETER	L’un des paramètres contient une valeur qui n’est pas valide. Il s’agit le plus souvent d’un pointeur qui n’est pas valide.
NTE_BAD_UID	Le paramètre hProv ne contient pas de handle de contexte valide.
NTE_FAIL	La fonction a échoué d’une manière inattendue.

Remarques

Les données produites par cette fonction sont aléatoires de manière cryptographique. Il est beaucoup plus aléatoire que les données générées par le générateur de nombres aléatoires standard, comme celui fourni avec votre compilateur C.

Cette fonction est souvent utilisée pour générer des vecteurs d’initialisation aléatoires et des valeurs de sel.

Les générateurs de nombres aléatoires logiciels fonctionnent fondamentalement de la même manière. Ils commencent par un nombre aléatoire, connu sous le nom de seed, puis utilisent un algorithme pour générer une séquence pseudo-aléatoire de bits basée sur celui-ci. La partie la plus difficile de ce processus est d’obtenir une graine vraiment aléatoire. Cela est généralement basé sur la latence d’entrée utilisateur ou la gigue d’un ou plusieurs composants matériels.

Avec microsoft CSP, CryptGenRandom utilise le même générateur de nombres aléatoires que celui utilisé par d’autres composants de sécurité. Cela permet à de nombreux processus de contribuer à une semence à l’échelle du système. CryptoAPI stocke une graine aléatoire intermédiaire avec chaque utilisateur. Pour former le seed pour le générateur de nombres aléatoires, une application appelante fournit des bits qu’elle peut avoir (pour instance, l’entrée de minutage de la souris ou du clavier) qui sont ensuite combinés à la fois à l’amorçage stocké et à diverses données système et utilisateur telles que l’ID de processus et l’ID de thread, l’horloge système, l’heure système, le compteur système, mémoire status, clusters de disque libres, bloc d’environnement utilisateur haché. Ce résultat est utilisé pour amorcer le générateur de nombres pseudorandom (PRNG). Dans Windows Vista avec Service Pack 1 (SP1) et versions ultérieures, une implémentation du prng basé sur le mode de contre-AES spécifié dans la publication spéciale NIST 800-90 est utilisée. Dans Windows Vista, Windows Storage Server 2003 et Windows XP, le PRNG spécifié dans Federal Information Processing Standard (FIPS) 186-2 est utilisé. Si une application a accès à une bonne source aléatoire, elle peut remplir la mémoire tampon pbBuffer avec des données aléatoires avant d’appeler CryptGenRandom. Le csp utilise ensuite ces données pour aléatoirer davantage sa semence interne. Il est acceptable d’omettre l’étape d’initialisation de la mémoire tampon pbBuffer avant d’appeler CryptGenRandom.

Exemples

L’exemple suivant montre la génération de 8 octets aléatoires. Elles peuvent être utilisées pour créer des clés de chiffrement ou pour toute application qui utilise des nombres aléatoires. Pour obtenir un exemple qui inclut le contexte complet de cet exemple, consultez Exemple de programme C : duplication d’une clé de session.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wincrypt.h
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll

Voir aussi

CryptAcquireContext

CryptGenKey

CryptSetKeyParam

Génération de clés et fonctions Exchange

Partager via