diff --git a/NEWS b/NEWS index a3764a8..ea28206 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,14 @@ +Since 0.9.8: + - When compiled with the CFLAG FAKE_RANDOM set, + libfaketime will intercept calls to getrandom() + and return pseudorandom numbers for determinism. + The mechanism needs to be activated by setting + the environment variable FAKERANDOM_SEED to a + 64-bit seed value, e.g., "0x12345678DEADBEEF". + Please note that this completely breaks the + security of random numbers for cryptographic + purposes and should only be used for deterministic + tests. Never use this in production! - When the environment variable FAKETIME_TIMESTAMP_FILE is set, points to a writeable (creatable) custom config file and the environment variable FAKETIME_UPDATE_TIMESTAMP_FILE @@ -7,8 +18,6 @@ - Additional link-time LDFLAGS can be passed via the environment variable FAKETIME_LINK_FLAGS when running 'make'. - -Since 0.9.8: - Compile-time CFLAG FAKE_SETTIME can be enabled to intercept calls to clock_settime(), settimeofday(), and adjtime(). (suggested and prototyped by @ojura) diff --git a/README b/README index ea9287d..ee56781 100644 --- a/README +++ b/README @@ -20,6 +20,7 @@ Content of this file: i) "Limiting" libfaketime per process j) Spawning an external process k) Saving timestamps to file, loading them from file + l) Replacing random numbers with deterministic number sequences (experimental) 5. License 6. Contact @@ -716,6 +717,41 @@ faketime needs to be run using the faketime wrapper to use these files. This functionality has been added by Balint Reczey in v0.9.5. +4l) Replacing random numbers with deterministic number sequences (experimental) +------------------------------------------------------------------------------- + +libfaketime can be compiled with the CFLAG FAKE_RANDOM set (see src/Makefile). + +When compiled this way, libfaketime additionally intercepts calls to the +function getrandom(), which currently is Linux-specific. + +This functionality is intended to feed a sequence of deterministic, repeatable +numbers to applications, which use getrandom(), instead of the random numbers +provided by /dev/[u]random. + +For creating the deterministic number sequence, libfaketime internally +uses Bernard Widynski's Middle Square Weyl Sequence Random Number Generator, +see https://mswsrng.wixsite.com/rand. + +It requires a 64-bit seed value, which has to be passed via the environment +variable FAKERANDOM_SEED, as in, for example + + LD_PRELOAD=src/libfaketime.so.1 \ + FAKERANDOM_SEED="0x12345678DEADBEEF" \ + test/getrandom_test + +Whenever the same seed value is used, the same sequence of "random-looking" +numbers is generated. + +Please be aware that this definitely breaks any security properties that +may be attributed to random numbers delivered by getrandom(), e.g., in the +context of cryptographic operations. Use it for deterministic testing +purposes only. Never use it in production. + +For a discussion on why this apparently not date-/time-related function +has been added to libfaketime and how it may evolve, see Github issue #275. + + 5. License ----------