getrandom(2) System Calls Manual getrandom(2) NOM getrandom - obtenir une serie d'octets aleatoires BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include ssize_t getrandom(void buf[.buflen], size_t buflen, unsigned int flags); DESCRIPTION L'appel systeme getrandom() remplit le tampon vers lequel pointe buf avec jusqu'a buflen octets aleatoires. Ces octets peuvent etre utilises pour alimenter des generateurs de nombre aleatoire dans l'espace utilisateur ou a des fins de chiffrement. Par defaut, getrandom() dessine une entropie a partir d'une source urandom (soit la meme source que le peripherique /dev/urandom). Ce comportement peut etre modifie avec le parametre flags. Si la source urandom a ete initialisee, les lectures jusqu'a 256 octets renverront toujours autant d'octets que demande et ne seront pas interrompues par des signaux. Il n'y a pas une telle garantie pour les tampons plus gros. Par exemple, si l'appel est interrompu par un gestionnaire de signal, il peut renvoyer un tampon partiellement rempli ou echouer avec l'erreur EINTR. Si la source urandom n'a pas encore ete initialisee, getrandom() se bloquera, sauf si GRND_NONBLOCK est indique dans flags. Le parametre flags est un masque de bit qui peut contenir aucune ou plusieurs des valeurs suivantes unies (OU logique) ensemble : GRND_RANDOM Si ce bit est positionne, les octets aleatoires seront dessines a partir de la source random (soit la meme que le peripherique /dev/random) au lieu de la source urandom. La source random est limitee par l'entropie qui peut etre recuperee a partir du bruit de l'environnement. Si le nombre d'octets disponibles dans la source random est inferieur a celui demande dans buflen, l'appel ne renvoie que les octets aleatoires disponibles. S'il n'y pas d'octets aleatoires disponibles, le comportement depend de la presence de GRND_NONBLOCK dans le parametre flags. GRND_NONBLOCK Par defaut, pendant une lecture depuis la source random, getrandom() se bloque si aucun octet aleatoire n'est disponible, tandis que pendant une lecture a partir de la source urandom, il se bloque si la reserve (pool) d'entropie n'a pas encore ete initialisee. Si le parametre GRND_NONBLOCK est positionne, getrandom() ne se bloque pas dans ces cas, mais il renvoie immediatement -1 et il positionne errno sur EAGAIN. VALEUR RENVOYEE En cas de succes, getrandom() renvoie le nombre d'octets copies dans le tampon buf. Il peut etre inferieur au nombre d'octets demande par buflen si GRND_RANDOM a ete indique dans flags et qu'il n'y avait pas assez d'entropie dans la source random, ou si l'appel systeme a ete interrompu par un signal. En cas d'erreur, la valeur de retour est -1 et errno est definie pour preciser l'erreur. ERREURS EAGAIN L'entropie demandee n'etait pas disponible et getrandom() se serait bloque si le parametre GRND_NONBLOCK n'avait pas ete positionne. EFAULT L'adresse a laquelle renvoie buf est en dehors de l'espace d'adressage accessible. EINTR L'appel a ete interrompu par un gestionnaire de signal ; voir la description sur la maniere dont sont geres les appels read(2) interrompus sur des peripheriques << lents >> avec et sans l'attribut SA_RESTART dans la page de manuel de signal(7). EINVAL Un parametre non valable a ete indique dans flags. ENOSYS La fonction enveloppe de la glibc pour getrandom() a determine que le noyau sous-jacent n'implemente pas cet appel systeme. STANDARDS Linux. HISTORIQUE Linux 3.17, glibc 2.25. NOTES Pour un apercu et une comparaison des interfaces utilisables pour produire de l'aleatoire, voir random(7). Contrairement a /dev/random et a /dev/urandom, getrandom() n'implique pas d'utiliser des noms de chemin ou des descripteurs de fichier. Ainsi, getrandom() peut etre utile dans les cas ou chroot(2) rend invisibles les noms de chemin /dev, et ou une application (comme un demon qui demarre) ferme un descripteur de fichier pour un de ces fichiers ouverts par une bibliotheque. Nombre maximal d'octets renvoyes A partir de Linux 3.19, les limites suivantes s'appliquent : - Pendant une lecture a partir d'une source urandom, un maximum de 32Mi-1 octets est renvoye par un appel getrandom() sur des systemes ou int a une taille de 32 bits. - Lors d'une lecture a partir d'une source random, un maximum de 512 octets est renvoye. Interruption par un gestionnaire de signal Lors de la lecture a partir d'une source urandom (GRND_RANDOM n'est pas positionne), getrandom() se bloquera jusqu'a ce que la reserve (pool) d'entropie soit initialisee (sauf si l'attribut GRND_NONBLOCK a ete indique). Si une demande est faite pour lire un grand nombre d'octets (plus de 256), getrandom() se bloquera jusqu'a ce que ces octets soient generes et transferes de la memoire du noyau vers buf. Lors d'une lecture a partir d'une source random (GRND_RANDOM est positionne), getrandom() se bloquera jusqu'a ce que des octets aleatoires soient disponibles (sauf si l'attribut GRND_NONBLOCK a ete indique). Quand un appel getrandom() se bloque pendant la lecture a partir d'une source urandom du fait d'une interruption par un gestionnaire de signal, le comportement depend de l'etat d'initialisation du tampon d'entropie et de la taille de la requete, buflen. Si la reserve d'entropie n'est pas encore initialisee, l'appel echoue avec l'erreur EINTR. Si cette reserve d'entropie a ete initialisee et si la taille de la requete est importante (buflen > 256), soit l'appel reussit, en renvoyant un tampon partiellement rempli, soit il echoue avec l'erreur EINTR. Si la reserve d'entropie a ete initialisee et si la taille demandee est petite (buflen <= 256), getrandom() n'echouera pas avec EINTR. Il renverra plutot tous les octets demandes. Pendant une lecture avec une source random, les requetes bloquantes de n'importe quelle taille peuvent etre interrompues par un gestionnaire de signal (l'appel echoue avec l'erreur EINTR). L'utilisation de getrandom() pour lire de petits tampons (<= 256 octets) a partir d'une source urandom est le cas d'utilisation privilegie. Le traitement particulier des petites valeurs de buflen a ete concu a des fins de compatibilite avec le getentropy(3) d'OpenBSD, qui est aujourd'hui gere par la glibc. L'utilisateur de getrandom() doit toujours verifier la valeur renvoyee, pour savoir si une erreur s'est produite ou si moins d'octets que le nombre demande ont ete renvoyes. Au cas ou GRND_RANDOM n'est pas indique et ou buflen est inferieur ou egal a 256, il ne devrait jamais y avoir de renvoi d'un nombre d'octets inferieur a celui demande, mais un programmeur prudent le verifiera quand meme. BOGUES A partir de Linux 3.19, le bogue suivant existe : - Selon la charge du processeur, getrandom() ne reagit pas aux interruptions avant de lire tous les octets demandes. VOIR AUSSI getentropy(3), random(4), urandom(4), random(7), signal(7) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 getrandom(2)