Skip to content
planet36Public

About

arc4random-compatible C library for modern Linux that uses a pool of random bytes generated by AES instructions

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

AES-CTR Random Pool (randp)

AES-CTR Random Pool (also known as randp) is a C library, designed for modern x86-64 Linux systems, with functions that give pseudorandom numbers. It was inspired by arc4random, and it mimics its functionality.

API

The API is designed to be compatible with the arc4random family of functions.

Description arc4random family randp family
Fill a buffer with n random bytes void arc4random_buf(void* buf, size_t n) void randp_bytes(void* buf, size_t n)
Return a uniform random unsigned integer uint32_t arc4random() uint8_t randp_u8()
uint16_t randp_u16()
uint32_t randp_u32()
uint64_t randp_u64()
Return a uniform random unsigned integer less than upper_bound uint32_t arc4random_uniform(uint32_t upper_bound) uint32_t randp_lt_u32(uint32_t upper_bound)
uint64_t randp_lt_u64(uint64_t upper_bound)

Design

The randp structure stores random bytes in a pool that can be retrieved later by the functions listed above.

Each thread has its own randp structure, so the functions need no locking. The structure is mmapd with flags MAP_PRIVATE | MAP_ANONYMOUS and then madvised with MADV_DONTDUMP and MADV_WIPEONFORK. A static thread_local pointer refers to it. Its size is at most one page (4096 B). It's not allocated until immediately before first use. When a thread exits, a C11 thread-specific storage destructor munmaps its structure. See src/allocate.h for details.

Description of mmap flags
MAP_PRIVATE
       Create a private copy-on-write mapping.  Updates to the
       mapping are not visible to other processes mapping the
       same file, and are not carried through to the underlying
       file.  It is unspecified whether changes made to the file
       after the mmap() call are visible in the mapped region.
MAP_ANONYMOUS
       The mapping is not backed by any file; its contents are
       initialized to zero.  The fd argument is ignored; however,
       some implementations require fd to be -1 if MAP_ANONYMOUS
       (or MAP_ANON) is specified, and portable applications
       should ensure this.  The offset argument should be zero.
       Support for MAP_ANONYMOUS in conjunction with MAP_SHARED
       was added in Linux 2.4.
Description of madvise flags
MADV_DONTDUMP (since Linux 3.4)
       Exclude from a core dump those pages in the range
       specified by addr and length.  This is useful in
       applications that have large areas of memory that are
       known not to be useful in a core dump.  The effect of
       MADV_DONTDUMP takes precedence over the bit mask that is
       set via the /proc/pid/coredump_filter file (see core(5)).
MADV_WIPEONFORK (since Linux 4.14)
       Present the child process with zero-filled memory in this
       range after a fork(2).  This is useful in forking servers
       in order to ensure that sensitive per-process data (for
       example, PRNG seeds, cryptographic secrets, and so on) is
       not handed to child processes.

       The MADV_WIPEONFORK operation can be applied only to
       private anonymous pages (see mmap(2)).

       Within the child created by fork(2), the MADV_WIPEONFORK
       setting remains in place on the specified address range.
       This setting is cleared during execve(2).

The structure is also mlocked to keep it out of swap. Locked memory counts against a per-process limit (RLIMIT_MEMLOCK), and each thread's structure takes one page of it, as does any memory the program itself locks. Once the limit is reached, mlock fails. In that case, randp uses the structure unlocked rather than terminate the program, so the structure can be swapped out.

Description of mlock
       mlock(), mlock2(), and mlockall() lock part or all of the
       calling process's virtual address space into RAM,
       preventing that memory from being paged to the swap area.
       mlock() locks pages in the address range starting at addr
       and continuing for size bytes.  All pages that contain a
       part of the specified address range are guaranteed to be
       resident in RAM when the call returns successfully; the
       pages are guaranteed to stay in RAM until later unlocked.

Upon first use, the pseudorandom number generator (PRNG) is seeded by getentropy. See src/aes_ctr_128_prng.h, or src/aes_ctr_256_prng.h in a VAES build, for details. Then the pool is filled with random bytes generated by the PRNG.

As bytes are retrieved from the pool, they are zeroized. When the pool is depleted, the PRNG generates a fresh pool of random bytes. After a set number of such refills, the PRNG itself is reseeded via getentropy before generating the next pool. See src/randp.c for details.

The pool size, the reseed interval, and the PRNG parameters are compile-time constants. To change one, edit its default in src/randp-defaults.h, src/aes_ctr_128_prng-defaults.h, or src/aes_ctr_256_prng-defaults.h, and rebuild. The benchmarks help pick the values.

Dependencies

To build and use randp

  • An x86-64 processor with AES instructions and SSE4.1 (x86-64-v2)
  • Linux 4.14 or newer
  • GCC 14 or newer
    • The -std=c23 option was added in GCC 14. randp uses C23 features such as constexpr, nullptr, typeof, and thread_local.
    • clang and clang++ are not supported.
  • Glibc 2.34 or newer
    • getentropy was added in glibc 2.25. 1 2
    • explicit_bzero was added in glibc 2.25.
    • C11 threads (tss_create, tss_set, call_once) were implemented in glibc 2.28, but lived only in libpthread. 3 randp doesn't link with -lpthread, so it needs glibc 2.34, where libpthread was merged into libc. 4

Build

The version comes from the latest git tag, so a build outside a tagged git checkout needs VERSION=X.Y passed to make.

  • make
    • Build the libraries, the header-only file, the pkg-config file, the tests, and the benchmarks.
    • The tests and benchmarks have their own dependencies.
  • make install
    • Build and install only the libraries, the headers, and the pkg-config file.
    • PREFIX (default /usr/local) and DESTDIR set where they go.

Link with -lrandp, or get the flags from pkg-config --cflags --libs randp.

VAES build

The default build targets x86-64-v2 and uses src/aes_ctr_128_prng.h, which works on 128-bit vectors. A VAES build uses src/aes_ctr_256_prng.h instead, which works on 256-bit vectors so each instruction processes two AES blocks. To make one, comment out the -march=x86-64-v2 -maes line in config.mk and uncomment the -march=x86-64-v3 -maes -mvaes line below it. The resulting library needs an x86-64-v3 processor with VAES.

Header-only

Run make randp-single.h to generate a header-only file of randp. It defines every function as static, so each translation unit that includes it gets its own copy of the code and its own per-thread pool, seeded separately.

FAQ

Is randp a cryptographically secure pseudorandom number generator (CSPRNG)?

No claims are made that randp is a CSPRNG, but the random numbers it produces are practically unpredictable (i.e., computationally infeasible to predict). It is built on AES, and it is seeded and periodically reseeded by getentropy. It lacks three things a CSPRNG claim needs: a formal security proof, independent review by third parties, and compliance with a standard such as NIST SP 800-90A.

License

randp is licensed under the Mozilla Public License 2.0 (MPL-2.0).

Footnotes

  1. https://sourceware.org/legacy-ml/libc-alpha/2017-02/msg00079.html ↩

  2. https://sourceware.org/bugzilla/show_bug.cgi?id=17252#c7 ↩

  3. https://lists.gnu.org/archive/html/info-gnu/2018-08/msg00000.html ↩

  4. https://developers.redhat.com/articles/2021/12/17/why-glibc-234-removed-libpthread ↩

About

arc4random-compatible C library for modern Linux that uses a pool of random bytes generated by AES instructions

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Contributors

Languages