[PATCH v2] bsp-howto: Add getentropy.

[Christian Mauderer]

From: Christian Mauderer <Christian.Mauderer at embedded-brains.de>

---
 bsp-howto/getentropy.rst | 32 ++++++++++++++++++++++++++++++++
 bsp-howto/index.rst      |  1 +
 2 files changed, 33 insertions(+)
 create mode 100644 bsp-howto/getentropy.rst

diff --git a/bsp-howto/getentropy.rst b/bsp-howto/getentropy.rst
new file mode 100644
index 0000000..b4a5599
--- /dev/null
+++ b/bsp-howto/getentropy.rst
@@ -0,0 +1,32 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2017 embedded brains GmbH <rtems at embedded-brains.de>
+.. COMMENT: All rights reserved.
+
+Entropy Source
+**************
+
+.. warning::
+    A good entropy source is critical for (nearly) all cryptographic
+    applications. The default implementation based on the cpu counter is not
+    suitable for such applications.
+
+The `arc4random` support in newlib needs an entropy source provided by the
+system. Therefore every BSP has to implement the :c:func:`getentropy` function.
+This function has to fill a memory region with a given size with random numbers
+and return `0` on success.
+
+In general for embedded systems it's not easy to get some real entropy. Normally
+that can only be reached with some extra hardware support. Some microcontrollers
+integrate a true random number generator or something similar for cryptographic
+applications. That is the preferred source of entropy for most BSPs. For example
+the atsam BSP uses the TRNG for it's entropy source (see
+`arm/atsam/random/random.c`).
+
+There is also a quite limited default implementation based on the CPU counter.
+It can be found in `libbsp/shared/getentropy-cpucounter-based.c`. Due to the
+fact that it is a time based source, the values provided by getentropy are quite
+predictable. This implementation is not appropriate for any cryptographic
+applications but it is good enough for some basic tasks. Use it only if you
+don't have any strong requirements on the entropy and if there is no better
+source.
diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst
index 67e31d2..de93be0 100644
--- a/bsp-howto/index.rst
+++ b/bsp-howto/index.rst
@@ -49,6 +49,7 @@ to the Community Project hosted at http://www.rtems.org/.
 	initilization_code
 	console
 	clock
+	getentropy
 	i2c
 	spi
 	real_time_clock
-- 
2.12.3