From 6e52616d55b47c0a67adbb336e82584e34ee3a28 Mon Sep 17 00:00:00 2001
From: Andy Chu <andychu@google.com>
Date: Tue, 11 Nov 2014 17:15:35 -0800
Subject: [PATCH] First pass of doc about randomness.  This won't be that
 practically useful until we have more client implementations.

---
 build.sh          |  1 +
 doc/randomness.md | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 doc/randomness.md

diff --git a/build.sh b/build.sh
index 2e23689..2a7064a 100755
--- a/build.sh
+++ b/build.sh
@@ -65,6 +65,7 @@ doc() {
   # TODO: generated docs
   run-markdown <README.md >_tmp/README.html
   run-markdown <doc/tutorial.md >_tmp/doc/tutorial.html
+  run-markdown <doc/randomness.md >_tmp/doc/randomness.html
 
   log 'Wrote docs to _tmp'
 }
diff --git a/doc/randomness.md b/doc/randomness.md
new file mode 100644
index 0000000..7136cdc
--- /dev/null
+++ b/doc/randomness.md
@@ -0,0 +1,38 @@
+Generating Random Bits for RAPPOR
+=================================
+
+To ensure privacy, an application using RAPPOR must generate random bits in an
+unpredictable manner.  In other words, an adversary that can predict the
+sequence of random bits used can determine the true values being reported.
+
+Generating random numbers is highly platform-specific -- even
+language-specific.  So, libraries implementing RAPPOR should be parameterized
+by an interface to generate random bits.  (This can be thought of as
+"dependency injection".)
+
+<!-- TODO: details on the interfaces, once we have them in more than one
+     language -->
+
+
+For now, we have collected some useful links.
+
+Linux
+-----
+
+* [Myths about /dev/urandom](http://www.2uo.de/myths-about-urandom/) -- Nice
+  article explaining implementation aspects of `/dev/urandom` and `/dev/random`
+  on Linux.  (Summary: just use `/dev/urandom`, with caveats explained)
+
+* [LWN on getrandom](http://lwn.net/Articles/606141/)
+  ([patch](http://lwn.net/Articles/605828/)) -- A very recent addition to the
+  Linux kernel.  As of this writing (11/2014), it's safe to say that very few
+  applications use it.  The relevant change, involving an issue mentioned in
+  the first link, involves the situation at system boot, when there is little
+  entropy available.
+
+
+<!-- TODO: other platforms.  Chrome uses /dev/urandom on Linux.  What about
+     other platforms?  -->
+
+<!-- TODO: when we have a C/C++ client, explain provide sample implementation
+     using simple C functions -->