[PATCH v2] bsp-howto: Add getentropy.

[Christian Mauderer]

Am 16.11.2017 um 18:17 schrieb 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.

Hello Gedare,

thanks for the hint. That is the disadvantage when writing a document in
a foreign language: I nearly have no chance to see such mistakes. But
I'm quite satisfied if that is the only one you found ;-)

Sebastian fixed that and checked it in.

Regards

Christian

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

-- 
--------------------------------------------
embedded brains GmbH
Christian Mauderer
Dornierstr. 4
D-82178 Puchheim
Germany
email: christian.mauderer at embedded-brains.de
Phone: +49-89-18 94 741 - 18
Fax:   +49-89-18 94 741 - 08
PGP: Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.