getrandom(2) System Calls Manual getrandom(2) NAZWA getrandom - pozyskuje serie losowych bajtow BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include ssize_t getrandom(void buf[.buflen], size_t buflen, unsigned int flags); OPIS Wywolanie systemowe getrandom() wypelnia bufor wskazywany przez buf do wielkosci buflen losowych bajtow. Bajtow tych mozna uzyc jako ziarna dla generatorow liczb losowych w przestrzeni uzytkownika, do celow kryptograficznych. Domyslnie, getrandom() pozyskuje entropie ze zrodla urandom (tj. tego samego zrodla, co urzadzenie /dev/urandom). To zachowanie mozna zmienic argumentem flags. Jesli zrodlo urandom zostalo zainicjowane, odczyt do 256 bajtow zawsze zwroci tak duzo bajtow, jak zazadano i nie bedzie przerywany sygnalami. Gwarancji takiej nie ma dla wiekszych buforow. Na przyklad, jesli wywolanie zostanie przerwane przez procedure obslugi sygnalu, moze zwrocic czesciowo wypelniony bufor lub zawiesc z bledem EINTR. Jesli zrodlo urandom nie zostalo zainicjowane, getrandom() zablokuje, chyba ze we flags podano GRND_NONBLOCK. Argument flags jest maska bitowa, ktora moze zawierac sume (OR) zera lub wiecej ponizszych wartosci: GRND_RANDOM Jesli ten bit jest ustawiony, to losowe bajty sa pozyskiwane ze zrodla random (tj. tego samego zrodla, co urzadzenie /dev/random), zamiast ze zrodla urandom. Zrodlo random jest ograniczone, w zaleznosci od entropii, jaka moze zostac pozyskana z szumu srodowiskowego. Jesli liczba dostepnym bajtow w zrodle random jest mniejsza, niz zadana w buflen, to wywolanie zwroci jedynie dostepne bajty losowe. Jesli w ogole brak jest dostepnych losowych bajtow, zachowanie zalezy od obecnosci GRND_NONBLOCK w argumencie flags. GRND_NONBLOCK Domyslnie, przy odczycie ze zrodla random, getrandom() blokuje, gdy brak jest dostepnych losowych bajtow, a przy odczycie ze zrodla urandom blokuje, gdy pula entropii nie zostala jeszcze zainicjowana. Jesli ustawiony jest znacznik GRND_NONBLOCK, to getrandom() w tych przypadkach nie blokuje, lecz natychmiast zwraca -1, z errno ustawionym na EAGAIN. WARTOSC ZWRACANA Przy powodzeniu, getrandom() zwraca liczbe bajtow skopiowanych do bufora buf. Moze byc ona mniejsza, niz liczba bajtow zadanych za pomoca buflen, jesli we flags podano GRND_RANDOM i w zrodle random byla obecna niewystarczajaca entropia, albo jesli wywolanie systemowe zostalo przerwane sygnalem. W razie wystapienia bledu zwracane jest -1 i ustawiane errno wskazujac blad. BLEDY EAGAIN Zadana entropia nie byla dostepna i getrandom() zablokowaloby, gdyby nie byl ustawiony znacznik GRND_NONBLOCK. EFAULT Adres, do ktorego odnosi sie buf byl poza dostepna przestrzenia adresowa. EINTR Wywolanie systemowe zostalo przerwane procedura obslugi sygnalu; zob. opis w podreczniku signal(7), jak obslugiwane jest przerwane wywolanie read(2) na ,,powolnych" urzadzeniach z, oraz bez, znacznika SA_RESTART. EINVAL We flags podano nieprawidlowy znacznik. ENOSYS Funkcja opakowujaca getrandom() z glibc ustalila, ze biezace jadro nie implementuje tego wywolania systemowego. STANDARDY Linux. HISTORIA Linux 3.17, glibc 2.25. UWAGI Przeglad i porownanie roznych interfejsow do pozyskiwania losowosci znajduje sie w podreczniku random(7). W przeciwienstwie do /dev/random i /dev/urandom, getrandom() nie angazuje sciezek, ani deskryptorow plikow. Z tego powodu getrandom() moze byc uzyteczne w przypadkach, gdy chroot(2) czyni sciezki /dev niewidocznymi oraz gdy aplikacja (np. demon w trakcie rozruchu) zamyka deskryptor pliku jednego z tych plikow, ktory byl otwarty przez biblioteke. Maksymalna liczba zwracanych bajtow Wedlug stanu na Linuksa 3.19 istnieja nastepujace limity: o Przy odczycie ze zrodla urandom, w systemach gdzie int ma rozmiar 32 bitow, pojedynczym wywolaniem do getrandom zwracanych jest maksymalnie 32Mi-1 bajtow. o Przy odczycie ze zrodla random, zwracanych jest co najwyzej 512 bajtow. Przerwanie procedura obslugi sygnalu Przy odczycie ze zrodla urandom (nie jest ustawiony GRND_RANDOM), getrandom() zablokuje, dopoki nie zostanie zainicjowana pula entropii (chyba, ze podano znacznik GRND_NONBLOCK). Jesli zadano odczytu duzej liczby bajtow (powyzej 256), getrandom() zablokuje, dopoki bajty te nie zostana wygenerowane i przeniesione z pamieci jadro do buf. Przy odczycie ze zrodla random (jest ustawiony GRND_RANDOM), getrandom() zablokuje, dopoki jakies losowe bajty nie stana sie dostepne (chyba, ze podano znacznik GRND_NONBLOCK). Zachowanie, gdy wywolanie do zablokowanego w trakcie odczytu ze zrodla urandom getrandom(), zostanie przerwane procedura obslugi sygnalu, zalezy od stanu zainicjowania bufora entropii oraz od zadanego rozmiaru w buflen. Jesli entropia nie zostala jeszcze zainicjowana, to wywolanie zawiedzie z bledem EINTR. Jesli pula entropii zostala zainicjowana, a zadany rozmiar jest duzy (buflen > 256), to wywolanie albo powiedzie sie, zwracajac czesciowo wypelniony bufor, albo zawiedzie z bledem EINTR. Jesli pula entropii zostala zainicjowana, a zadany rozmiar jest maly (buflen <= 256), to getrandom() nie zawiedzie z EINTR, lecz zwroci wszystkie zadane bajty. Przy odczycie ze zrodla random, blokujace zadania o dowolnym rozmiarze moga byc przerwane procedura obslugi sygnalu (wywolanie zawiedzie z bledem EINTR). Preferowana metoda korzystania z getrandom(), jest odczyt malych buforow (<= 256 bajtow) ze zrodla urandom. Specjalny sposob traktowania malych wartosci buflen zostal zaprojektowany w celu zachowania kompatybilnosci z getentropy(3) z OpenBSD, ktore jest obecnie obslugiwane w glibc. Uzytkownik getrandom() zawsze musi sprawdzac zwracana wartosc, aby okreslic, czy wystapil blad, czy tez zwrocono mniej bajtow niz zadano. W przypadku gdy nie poda sie GRND_RANDOM, a buflen jest mniejsze lub rowne 256, nigdy nie powinna wystapic sytuacja zwrocenia mniejszej liczby bajtow niz zadano, lecz ostrozny programista i tak powinien to sprawdzic! USTERKI Wedlug stanu na Linuksa 3.19, wystepuje ponizszy blad: o W zaleznosci od obciazenia procesora, getrandom() nie reaguje na przerwania, przed odczytem wszystkich zadanych bajtow. ZOBACZ TAKZE getentropy(3), random(4), urandom(4), random(7), signal(7) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.9.1 2 maja 2024 r. getrandom(2)