rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-05 22:14:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

bsp-howto: Add getentropy.

Browse Source 
Update #3239.
This commit is contained in:
Christian Mauderer 2017-11-16 16:01:16 +01:00 committed by Sebastian Huber
parent d9ecff105d
commit d0b961ac34
2 changed files with 40 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
bsp-howto/getentropy.rst Normal file
View File

@ -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.

1
bsp-howto/index.rst
View File

@ -49,6 +49,7 @@ to the Community Project hosted at http://www.rtems.org/.
initilization_code
console
clock
getentropy
i2c
spi
real_time_clock