[PATCH v2] bsp-howto: Add getentropy.

[Gedare Bloom]

On Thu, Nov 16, 2017 at 10:01 AM, Christian Mauderer
<christian.mauderer at embedded-brains.de> wrote:
> 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
Thanks! Minor nit: use "its" without the apostrophe for possessive
form. "it's" with the apostrophe is the contraction of "it is". One of
those English language exceptions.

> +`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
>