getrandom(2) System Calls Manual getrandom(2)
NOM
getrandom - obtenir une série d'octets aléatoires
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <sys/random.h>
ssize_t getrandom(void buf[.buflen], size_t buflen, unsigned int flags);
DESCRIPTION
L'appel système getrandom() remplit le tampon vers lequel pointe buf
avec jusqu'à buflen octets aléatoires. Ces octets peuvent être utilisés
pour alimenter des générateurs de nombre aléatoire dans l'espace utili-
sateur ou à des fins de chiffrement.
Par défaut, getrandom() dessine une entropie à partir d'une source
urandom (soit la même source que le périphérique /dev/urandom). Ce com-
portement peut être modifié avec le paramètre flags.
Si la source urandom a été initialisée, les lectures jusqu'à 256 octets
renverront toujours autant d'octets que demandé et ne seront pas inter-
rompues par des signaux. Il n'y a pas une telle garantie pour les tam-
pons plus gros. Par exemple, si l'appel est interrompu par un gestion-
naire de signal, il peut renvoyer un tampon partiellement rempli ou
échouer avec l'erreur EINTR.
Si la source urandom n'a pas encore été initialisée, getrandom() se
bloquera, sauf si GRND_NONBLOCK est indiqué dans flags.
Le paramètre 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 positionné, les octets aléatoires seront dessinés
à partir de la source random (soit la même que le périphérique
/dev/random) au lieu de la source urandom. La source random est
limitée par l'entropie qui peut être récupérée à partir du bruit
de l'environnement. Si le nombre d'octets disponibles dans la
source random est inférieur à celui demandé dans buflen, l'appel
ne renvoie que les octets aléatoires disponibles. S'il n'y pas
d'octets aléatoires disponibles, le comportement dépend de la
présence de GRND_NONBLOCK dans le paramètre flags.
GRND_NONBLOCK
Par défaut, pendant une lecture depuis la source random, getran-
dom() se bloque si aucun octet aléatoire n'est disponible, tan-
dis que pendant une lecture à partir de la source urandom, il se
bloque si la réserve (pool) d'entropie n'a pas encore été ini-
tialisée. Si le paramètre GRND_NONBLOCK est positionné, getran-
dom() ne se bloque pas dans ces cas, mais il renvoie immédiate-
ment -1 et il positionne errno sur EAGAIN.
VALEUR RENVOYÉE
En cas de succès, getrandom() renvoie le nombre d'octets copiés dans le
tampon buf. Il peut être inférieur au nombre d'octets demandé par bu-
flen si GRND_RANDOM a été indiqué dans flags et qu'il n'y avait pas as-
sez d'entropie dans la source random, ou si l'appel système a été in-
terrompu par un signal.
En cas d'erreur, la valeur de retour est -1 et errno est définie pour
préciser l'erreur.
ERREURS
EAGAIN L'entropie demandée n'était pas disponible et getrandom() se se-
rait bloqué si le paramètre GRND_NONBLOCK n'avait pas été posi-
tionné.
EFAULT L'adresse à laquelle renvoie buf est en dehors de l'espace
d'adressage accessible.
EINTR L'appel a été interrompu par un gestionnaire de signal ; voir la
description sur la manière dont sont gérés les appels read(2)
interrompus sur des périphériques « lents » avec et sans l'at-
tribut SA_RESTART dans la page de manuel de signal(7).
EINVAL Un paramètre non valable a été indiqué dans flags.
ENOSYS La fonction enveloppe de la glibc pour getrandom() a déterminé
que le noyau sous-jacent n'implémente pas cet appel système.
VERSIONS
getrandom() a été introduit dans Linux 3.17. La prise en charge a été
ajoutée dans la glibc 2.25.
STANDARDS
Cet appel système est spécifique à Linux.
NOTES
Pour un aperçu et une comparaison des interfaces utilisables pour pro-
duire de l'aléatoire, voir random(7).
Contrairement à /dev/random et à /dev/urandom, getrandom() n'implique
pas d'utiliser des noms de chemin ou des descripteurs de fichier.
Ainsi, getrandom() peut être utile dans les cas où chroot(2) rend invi-
sibles les noms de chemin /dev, et où une application (comme un démon
qui démarre) ferme un descripteur de fichier pour un de ces fichiers
ouverts par une bibliothèque.
Nombre maximal d'octets renvoyés
À partir de Linux 3.19, les limites suivantes s'appliquent :
• Pendant une lecture à partir d'une source urandom, un maximum de
32Mi-1 octets est renvoyé par un appel getrandom() sur des systèmes
où int a une taille de 32 bits.
• Lors d'une lecture à partir d'une source random, un maximum de 512
octets est renvoyé.
Interruption par un gestionnaire de signal
Lors de la lecture à partir d'une source urandom (GRND_RANDOM n'est pas
positionné), getrandom() se bloquera jusqu'à ce que la réserve (pool)
d'entropie soit initialisée (sauf si l'attribut GRND_NONBLOCK a été in-
diqué). Si une demande est faite pour lire un grand nombre d'octets
(plus de 256), getrandom() se bloquera jusqu'à ce que ces octets soient
générés et transférés de la mémoire du noyau vers buf. Lors d'une lec-
ture à partir d'une source random (GRND_RANDOM est positionné), getran-
dom() se bloquera jusqu'à ce que des octets aléatoires soient dispo-
nibles (sauf si l'attribut GRND_NONBLOCK a été indiqué).
Quand un appel getrandom() se bloque pendant la lecture à partir d'une
source urandom du fait d'une interruption par un gestionnaire de si-
gnal, le comportement dépend de l'état d'initialisation du tampon d'en-
tropie et de la taille de la requête, buflen. Si la réserve d'entropie
n'est pas encore initialisée, l'appel échoue avec l'erreur EINTR. Si
cette réserve d'entropie a été initialisée et si la taille de la re-
quête est importante (buflen > 256), soit l'appel réussit, en renvoyant
un tampon partiellement rempli, soit il échoue avec l'erreur EINTR. Si
la réserve d'entropie a été initialisée et si la taille demandée est
petite (buflen <= 256), getrandom() n'échouera pas avec EINTR. Il ren-
verra plutôt tous les octets demandés.
Pendant une lecture avec une source random, les requêtes bloquantes de
n'importe quelle taille peuvent être interrompues par un gestionnaire
de signal (l'appel échoue avec l'erreur EINTR).
L'utilisation de getrandom() pour lire de petits tampons (<= 256 oc-
tets) à partir d'une source urandom est le cas d'utilisation privilé-
gié.
Le traitement particulier des petites valeurs de buflen a été conçu à
des fins de compatibilité avec le getentropy(3) d'OpenBSD, qui est au-
jourd'hui géré par la glibc.
L'utilisateur de getrandom() doit toujours vérifier la valeur renvoyée,
pour savoir si une erreur s'est produite ou si moins d'octets que le
nombre demandé ont été renvoyés. Au cas où GRND_RANDOM n'est pas indi-
qué et où buflen est inférieur ou égal à 256, il ne devrait jamais y
avoir de renvoi d'un nombre d'octets inférieur à celui demandé, mais un
programmeur prudent le vérifiera quand même.
BOGUES
À partir de Linux 3.19, le bogue suivant existe :
• Selon la charge du processeur, getrandom() ne réagit pas aux inter-
ruptions avant de lire tous les octets demandés.
VOIR AUSSI
getentropy(3), random(4), urandom(4), random(7), signal(7)
TRADUCTION
La traduction française de cette page de manuel a été créée par Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, Fran-
çois Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Gué-
rard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.org>, David Prévot <david@tilapin.org> et Jean-Philippe MENGUAL
<jpmengual@debian.org>
Cette traduction est une documentation libre ; veuillez vous reporter à
la GNU General Public License version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les conditions
de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à ⟨debian-l10n-french@lists.debian.org⟩.
Pages du manuel de Linux 6.03 8 février 2023 getrandom(2)
Generated by dwww version 1.15 on Sat Jun 29 01:47:54 CEST 2024.