summaryrefslogtreecommitdiffstats
path: root/bsp-howto
diff options
context:
space:
mode:
authorChristian Mauderer <Christian.Mauderer@embedded-brains.de>2017-11-16 16:01:16 +0100
committerSebastian Huber <sebastian.huber@embedded-brains.de>2017-11-17 07:47:38 +0100
commitd0b961ac3492533c70ba886470c2b5b09bbeaf39 (patch)
tree0fbcd3fc2ca2b9d7561fa96b57e3f69274450f9b /bsp-howto
parentd9ecff105d5438158a994f106ca7f55b5c4e60e3 (diff)
downloadrtems-docs-d0b961ac3492533c70ba886470c2b5b09bbeaf39.tar.bz2
bsp-howto: Add getentropy.
Update #3239.
Diffstat (limited to 'bsp-howto')
-rw-r--r--bsp-howto/getentropy.rst39
-rw-r--r--bsp-howto/index.rst1
2 files changed, 40 insertions, 0 deletions
diff --git a/bsp-howto/getentropy.rst b/bsp-howto/getentropy.rst
new file mode 100644
index 0000000..b460450
--- /dev/null
+++ b/bsp-howto/getentropy.rst
@@ -0,0 +1,39 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. COMMENT: COPYRIGHT (c) 2017 embedded brains GmbH <rtems@embedded-brains.de>
+.. COMMENT: All rights reserved.
+
+Entropy Source
+**************
+
+Each BSP must provide an implementation of the :c:func:`getentropy` system
+call. This system call was introduced by
+`OpenBSD <https://man.openbsd.org/getentropy.2>`_
+and is also available in
+`glibc since version 2.25 <http://man7.org/linux/man-pages/man3/getentropy.3.html>`_.
+This system call is used by the Newlib provided
+`ARC4RANDOM(3) <https://man.openbsd.org/arc4random.3>`_ functions, which in
+turn are used by various cryptographic functions.
+
+.. 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 :c:func:`getentropy` implementation must fill the specified memory region
+of the given size with random numbers and return 0 on success.
+
+In general, for embedded systems it is 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 its entropy source <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/arm/atsam/startup/getentropy-trng.c>`_.
+
+There is also a quite limited
+`default implementation based on the CPU counter <https://git.rtems.org/rtems/tree/c/src/lib/libbsp/shared/getentropy-cpucounter.c>`_.
+Due to the fact that it is a time based source, the values provided by
+:c:func:`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 do not 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