examples: Overhaul fill_random #2003

pull real-or-random wants to merge 5 commits into bitcoin-core:master from real-or-random:202611-examples-fill-random changing 1 files +64 −29
  1. real-or-random commented at 2:37 PM on November 16, 2026: contributor

    This supersedes #1215.

    fill_random was added in 2022 (#748), and its implementation hasn't changed since, so after a few years, it's time for an overhaul. Since fill_random is meant to be copied into other code, it should be a good template. With this PR:

    • It works for arbitrary sizes. Currently, it doesn't on any platform: getentropy() (macOS, OpenBSD) fails for requests larger than 256 bytes, getrandom() (Linux, FreeBSD) may return fewer bytes than requested, which is treated as failure, and BCryptGenRandom() (Windows) takes a ULONG length.
    • It aborts on failure instead of returning an error (second commit). Callers can't do anything sensible on failure, and an error return in code that gets copied invites mishandling (e.g., ignoring the return value and using an unfilled buffer). Rust's std and BoringSSL don't return an error either: Rust's std panics, and BoringSSL aborts. Nonetheless, fill_random keeps returning int (now always 1 plus unreachable return 0 after abort()), and the examples keep checking it. People may copy fill_random without the examples, or the examples without fill_random, so both should be defensive on their own.
    • It no longer recommends falling back to /dev/urandom on Linux (third commit). A fallback matters only for Linux < 3.17, and simply reading from /dev/urandom isn't a correct fallback anyway because it doesn't wait for the entropy pool to be initialized.
    • It handles a request for 0 bytes consistently on all platforms by returning early (fourth commit). This is an edge case on which implementations may differ, e.g., NetBSD's arc4random_buf() passes the buffer pointer to memcpy() even for size 0, which is undefined behavior if the pointer is NULL. As a result, data can be NULL if size is 0, consistent with the library's API (e.g., the msg argument of secp256k1_schnorrsig_verify).
    • It supports NetBSD.

    Overview of randomness sources (after the PR)

    • Linux: getrandom() in a loop, retrying on EINTR
    • macOS and other Apple platforms: CCRandomGenerateBytes()
    • FreeBSD, NetBSD, OpenBSD: arc4random_buf(), which works for arbitrary sizes and never returns an error. The OpenBSD getentropy man page recommends it for ordinary random data.
    • Windows: BCryptGenRandom() in a loop over ULONG-sized chunks

    Side note: Since bitcoin/bitcoin#27699, Core detects getrandom() via <sys/random.h> (CMake check), which FreeBSD (>= 12) and NetBSD (>= 10) provide as well. So these presumably take the getrandom() branch, not the sysctl() branch whose comment says "FreeBSD, NetBSD and similar" (last touched in bitcoin/bitcoin#18359). @fanquake, is this intended?

    <details> <summary>

    Detailed rationale and background

    </summary>

    Why not arc4random_buf() on Linux

    On Linux, arc4random_buf() is not an option: it's not available in musl or glibc < 2.36, and glibc doesn't declare it under -std=c89 unless _DEFAULT_SOURCE is defined.

    Why CCRandomGenerateBytes() on Apple platforms

    On Apple platforms, arc4random_buf() and CCRandomGenerateBytes() draw from the same generator (since macOS 10.15), and Apple's getentropy man page recommends both for ordinary random data. But Apple's arc4random_buf() ignores the return value of the underlying generator, so a failure would silently leave the buffer unfilled, whereas CCRandomGenerateBytes() reports it. This should also make fill_random usable on iOS and other non-macOS Apple platforms, where getentropy() isn't public API (sys/random.h exists only in the macOS SDK), but I haven't tested this.

    What does Rust's std do?

    Apart from Rust's /dev/urandom fallback for Linux < 3.17, this ends up doing the same as Rust's std, which (like a C program) always links libc, with one deliberate exception: On Windows, Rust's std uses ProcessPrng(), which always succeeds and takes a SIZE_T length. However, the Windows SDK provides neither a declaration nor an import library for it, so it has to be loaded at runtime via LoadLibrary() and GetProcAddress() (as BoringSSL and Chromium do). That's too much ceremony for an example, so this PR keeps BCryptGenRandom().

    What does Bitcoin Core do?

    Where the requirements overlap, Bitcoin Core's GetOSRand() makes the same choices as this PR: it uses getrandom() on Linux, BCryptGenRandom() on Windows and arc4random_buf() on OpenBSD, and it aborts on failure. It differs elsewhere because it solves a different problem: it always requests exactly 32 bytes, which Core mixes into its own RNG together with other entropy sources. So it can rely on per-call limits (it calls getrandom() only once, relying on the guarantee for requests of up to 256 bytes, and it uses getentropy() on macOS). Moreover, it selects the API via build-time feature detection (HAVE_GETRANDOM, HAVE_GETENTROPY_RAND, HAVE_SYSCTL_ARND) with a fallback to /dev/urandom, which a header that people copy can't do.

    Minimum OS versions

    This doesn't raise any minimum OS version: CCRandomGenerateBytes() has been available since macOS 10.10, and arc4random_buf() since FreeBSD 8.0, NetBSD 6.0 and OpenBSD 4.4, i.e., before the getentropy()/getrandom() versions the current code requires (macOS 10.12, FreeBSD 12.0, OpenBSD 5.6). Earlier versions of these BSDs implemented arc4random with RC4, but it was replaced in FreeBSD 12.0, NetBSD 7.0 and OpenBSD 5.5. On all three BSDs, <stdlib.h> declares arc4random_buf() under -std=c89 without feature-test macros.

    </details>

  2. examples: Make fill_random work for arbitrary sizes
    Since fill_random is meant to be copied into other code, it should work
    for arbitrary sizes. Previously, it didn't on any platform. For example,
    getentropy, used on macOS and OpenBSD, fails for requests larger than
    256 bytes.
    
    On the BSDs, use arc4random_buf, as recommended by the OpenBSD man
    pages. This also adds support for NetBSD.
    
    On macOS, use CCRandomGenerateBytes, as Rust's std does. arc4random_buf
    would draw from the same generator (since macOS 10.15), but Apple's
    implementation ignores the generator's return value, so a failure would
    silently leave the buffer unfilled. CCRandomGenerateBytes reports such
    failures. CCRandomGenerateBytes is available since macOS 10.10 and iOS
    8.0, and libSystem re-exports it, so no additional linker flags are
    needed.
    
    Linux keeps getrandom. Even where glibc provides arc4random_buf, it
    doesn't declare it in -std=c89 mode unless _DEFAULT_SOURCE is defined
    before the first libc header is included.
    388d7bab02
  3. theStack commented at 4:32 PM on November 16, 2026: contributor

    Concept ACK

  4. in examples/examples_util.h:50 in 1e7af74e46
      50 |  
      51 | -/* Returns 1 on success, and 0 on failure. */
      52 | -static int fill_random(unsigned char* data, size_t size) {
      53 | +/* Fills `data` with `size` random bytes. `data` can only be NULL if `size` is 0.
      54 | + * Aborts on failure. */
      55 | +static void fill_random(unsigned char* data, size_t size) {
    


    real-or-random commented at 4:01 PM on November 17, 2026:

    Note to self: Aborting is better than returning 0 but maybe it's a good idea to keep the return type int and add an (unreachable) return 0 at the end.

    The goal here is to make the code fool-proof because people will copy it. And the issue now is that there are a) people who copy fill_random() but not the application examples, b) people who copy the application examples but not fill_random(). So ideally, we have "defensive" code in both places. And that means fill_random() aborting in case of failure but still callers of fill_random() checking for errors.


    real-or-random commented at 2:59 PM on November 18, 2026:

    Force-pushed and updated the PR description to fix this.

  5. real-or-random force-pushed on Nov 18, 2026
  6. examples: Abort in fill_random on failure
    Callers can't do anything sensible if the OS fails to provide
    randomness, and an error return in code that is meant to be copied
    invites mishandling, e.g., using the buffer without checking the return
    value. Rust's std and BoringSSL don't return an error either.
    
    Keep the return value, unreachable error returns, and the checks in the
    examples nonetheless, because people may modify fill_random, copy it
    without the examples, or copy the examples without it.
    
    Print the message to stderr because abort() doesn't necessarily flush
    stdout.
    ea9947d340
  7. examples: Drop advice to fall back to /dev/urandom on Linux
    getrandom has been available since Linux 3.17 (2014), so a fallback
    matters only on very old systems. Moreover, simply reading from
    /dev/urandom, as the comments suggested, is not a correct fallback: on
    kernels without getrandom, /dev/urandom returns output even before the
    entropy pool has been initialized.
    bf6d204e12
  8. examples: Return early from fill_random if size is 0
    Allowing data to be NULL if size is 0 is consistent with the library's
    API, e.g., the msg argument of secp256k1_schnorrsig_verify.
    9f06107db2
  9. examples: Use C89 comment in examples_util.h
    The // comment is in a block that only MSVC compiles, so the
    -std=c89 -pedantic builds didn't catch it.
    1240c668e6
  10. real-or-random force-pushed on Nov 18, 2026

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin-core/secp256k1. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-21 14:15 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me