[PATCH] bsp-howto: Add getentropy.

[Gedare Bloom]

Christian,

Thanks. Do we provide in the BSP guide examples to places that
implement optional features? This seems like a good place to mention
the atsam implementation as a reference for using hardware TRNG to
give a quick pointer for the interested developer.

Gedare

On Thu, Nov 16, 2017 at 7:44 AM, Christian Mauderer
<christian.mauderer at embedded-brains.de> wrote:
> From: Christian Mauderer <Christian.Mauderer at embedded-brains.de>
>
> ---
>  bsp-howto/getentropy.rst | 31 +++++++++++++++++++++++++++++++
>  bsp-howto/index.rst      |  1 +
>  2 files changed, 32 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..902d3e5
> --- /dev/null
> +++ b/bsp-howto/getentropy.rst
> @@ -0,0 +1,31 @@
> +.. 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. For example some
> +microcontrollers integrate a true random number generator or something similar
> +for cryptographic applications. That is the preferred source of entropy for most
> +BSPs.
> +
> +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
>