summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorOleksij Rempel <o.rempel@pengutronix.de>2017-05-09 07:34:04 +0200
committerSascha Hauer <s.hauer@pengutronix.de>2017-05-11 08:18:12 +0200
commitcf4c8c921e13d6d08c7869048186d6ac0996d58b (patch)
tree58e9b43c69346386a0d6b014b6f091c728fd4156
parent0bed8c578c8df18353495cde574b622e70fbcee5 (diff)
downloadbarebox-cf4c8c921e13d6d08c7869048186d6ac0996d58b.tar.gz
Documentation: provide documentation for RNG interfaces.
Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de> Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
-rw-r--r--Documentation/user/random.rst63
-rw-r--r--Documentation/user/user-manual.rst1
2 files changed, 64 insertions, 0 deletions
diff --git a/Documentation/user/random.rst b/Documentation/user/random.rst
new file mode 100644
index 0000000..95dad72
--- /dev/null
+++ b/Documentation/user/random.rst
@@ -0,0 +1,63 @@
+Random Number Generator support
+===============================
+
+Barebox provides two types of RNG sources - PRNG and HWRNG:
+
+- "A pseudorandom number generator (PRNG), also known as a deterministic random
+ bit generator (DRBG),[1] is an algorithm for generating a sequence of numbers
+ whose properties approximate the properties of sequences of random numbers.
+ The PRNG-generated sequence is not truly random, because it is completely
+ determined by a relatively small set of initial values, called the PRNG's seed
+ (which may include truly random values). Although sequences that are closer to
+ truly random can be generated using hardware random number generators."
+ Pseudorandom number generator. https://en.wikipedia.org/wiki/Pseudorandom_number_generator (2017.05.08).
+ The PRNG used by Barebox is LCG (linear congruential generator) non cryptographically
+ secure, so please use with caution.
+
+- The HWRNG framework is software that makes use of a special hardware feature on
+ your CPU, SoC or motherboard. It can‘t provide any guarantee about cryptographic
+ security of used HW. Please refer to vendor documentation and/or RNG certification.
+
+API
+^^^
+
+.. code-block:: c
+
+ /* seed the PRNG. */
+ void srand(unsigned int seed);
+
+ /* Fill the buffer with PRNG bits. */
+ void get_random_bytes(void *buf, int len);
+
+ /* Fill the buffer with bits provided by HWRNG.
+ * This function may fail with a message “error: no HWRNG available!”
+ * in case HWRNG is not available or HW got some runtime error.
+ * If barebox is compiled with CONFIG_ALLOW_PRNG_FALLBACK,
+ * then get_crypto_bytes() will print “warning: falling back to Pseudo RNG source!”
+ * and use PRNG instead of returning error.
+ */
+ int get_crypto_bytes(void *buf, int len);
+
+User interface
+^^^^^^^^^^^^^^
+
+- /dev/hwrng0
+ provides access to first available HWRNG. To examine this source you can use:
+
+.. code-block:: sh
+
+ md -s /dev/hwrng0
+
+- /dev/prng
+ provides access to PRNG. To examine this source you can use:
+
+.. code-block:: sh
+
+ md -s /dev/prng
+
+To seed PRNG from user space the :ref:`command_seed` is provided. For example:
+
+.. code-block:: sh
+
+ seed 12345
+ md -s /dev/prng
diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 435649f..791c8e0 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -33,6 +33,7 @@ Contents:
reset-reason
system-reset
state
+ random
* :ref:`search`
* :ref:`genindex`