1 files changed, 35 insertions, 0 deletions

diff --git a/DESIGN b/DESIGN
index eb8679e..39d0107 100644
--- a/DESIGN
+++ b/DESIGN
@@ -103,6 +103,41 @@ ordinary announce interval is a constant too and an operator has nothing to
 measure a different value against. Over HTTP a refusal stays a failure
 reason, which is the only place a user is told why.
 
+The state file keeps a wall clock minute, and it is the only thing in the
+tracker that reads that clock. Everything else runs off a monotonic one,
+where a time step cannot evict a swarm, but a file outlives the process that
+wrote it and minutes since this boot mean nothing to the next run. So the
+dump converts on the way out and load_state converts on the way back in, and
+what lands on disk is the format opentracker has written for years. A step
+between writing and reading mis-dates a torrent by the size of the step,
+which costs it part of its last day and nothing else.
+
+Build hardening the shipped binary
+----------------------------------
+
+The production and debug binaries carry -fstack-protector-strong, -fPIE and
+_FORTIFY_SOURCE=2 on every platform; the GNU-style linkers also get -pie and
+full RELRO (-z relro,-z now). Measured cost on
+the announce hot path is 300 to 305 nanoseconds, under two per cent, and the
+individual flags sit inside the run-to-run noise: add_peer has few stack
+buffers, most buffer sizes are known at compile time so FORTIFY emits no
+runtime check, and PIE on arm64 is almost free. On x86-64 PIE costs a little
+more. End to end it is invisible, since a UDP announce is mostly kernel time.
+
+The link flags -pie and RELRO are gated on the operating system: Apple's
+linker rejects -z, and flags a bare -pie in the combined compile-and-link as
+unused, while macOS links executables PIE by default, so leaving both off
+there costs no hardening. The branch runs in the shell through a != assignment,
+the one form both bmake and GNU make 4 accept; $(shell) is GNU only and GNU
+make 3.81, which stock macOS ships, has neither. On that old make the != line
+is inert and leaves the flags empty, which is the right answer for macOS
+anyway, so every platform resolves correctly without a make conditional.
+
+The flags are not in OT_CFLAGS, so the sanitizer test builds do not inherit
+them. AddressSanitizer checks harder than FORTIFY does, and the two clash on
+FreeBSD, where a FORTIFY plus ASan build aborted a multi hash scrape that the
+hardened production binary serves without complaint.
+
 Startup and teardown order
 --------------------------