diff options
author | Christian Mauderer <Christian.Mauderer@embedded-brains.de> | 2017-11-16 16:01:16 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2017-11-17 07:47:38 +0100 |
commit | d0b961ac3492533c70ba886470c2b5b09bbeaf39 (patch) | |
tree | 0fbcd3fc2ca2b9d7561fa96b57e3f69274450f9b /bsp-howto/getentropy.rst | |
parent | c-users: Clarify semaphore obtain/flush (diff) | |
download | rtems-docs-d0b961ac3492533c70ba886470c2b5b09bbeaf39.tar.bz2 |
bsp-howto: Add getentropy.
Update #3239.
Diffstat (limited to 'bsp-howto/getentropy.rst')
-rw-r--r-- | bsp-howto/getentropy.rst | 39 |
1 files changed, 39 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. |