* Re: [PATCH v1] Documentation: random: provide documentation.
[not found] <20170508123214.18608-1-o.rempel@pengutronix.de>
@ 2017-05-08 13:02 ` Yegor Yefremov
0 siblings, 0 replies; only message in thread
From: Yegor Yefremov @ 2017-05-08 13:02 UTC (permalink / raw)
To: Oleksij Rempel; +Cc: barebox
Hi Oleksij,
On Mon, May 8, 2017 at 2:32 PM, Oleksij Rempel <o.rempel@pengutronix.de> wrote:
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> ---
> Documentation/user/random.rst | 60 ++++++++++++++++++++++++++++++++++++++
> Documentation/user/user-manual.rst | 1 +
> 2 files changed, 61 insertions(+)
> create mode 100644 Documentation/user/random.rst
>
> diff --git a/Documentation/user/random.rst b/Documentation/user/random.rst
> new file mode 100644
> index 0000000000..075567ac59
> --- /dev/null
> +++ b/Documentation/user/random.rst
> @@ -0,0 +1,60 @@
> +Random Number Generator support
> +===============================
> +
> +Barebox is providing two types of RNG sources:
s/is providing/provides
> +- "A pseudorandom number generator (PRNG), also known as a deterministic random
> + bit generator (DRBG),[1] is an algorithm for generating a sequence of numbers
> + whose properties approximate the properties of sequences of random numbers.
> + The PRNG-generated sequence is not truly random, because it is completely
> + determined by a relatively small set of initial values, called the PRNG's seed
> + (which may include truly random values). Although sequences that are closer to
> + truly random can be generated using hardware random number generators."
> + Pseudorandom number generator. https://en.wikipedia.org/wiki/Pseudorandom_number_generator (2017.05.08).
> + The PRNG used by Barebox is LCG (linear congruential generator) non cryptographically
> + secure, so please use with caution.
> +
> +- The HWRNG framework is software that makes use of a special hardware feature on
> + your CPU, SoC or motherboard. It can‘t provide any guarantee about cryptographic
> + security of used HW. Please refer to vendor documentation and/or RNG certification.
> +
> +API
> +^^^
> +
> +.. code-block:: c
> +
> + /* seed the PRNG. */
> + void srand(unsigned int seed);
> +
> + /* Fill the buffer with PRNG bits. */
> + void get_random_bytes(void *buf, int len);
> +
> + /* Fill the buffer with bits provided by HWRNG.
> + * This function may fail with message “error: no HWRNG available!”
s/with message/with a message
> + * in case HWRNG is not available or HW got some runtime error.
> + * If barebox is compiled with CONFIG_ALLOW_PRNG_FALLBACK,
> + * then get_crypto_bytes() will print “warning: falling back to Pseudo RNG source!”
> + * and use PRNG instead of returning error.
> + */
> + int get_crypto_bytes(void *buf, int len);
> +
> +User interface
> +^^^^^^^^^^^^^^
> +
> +- /dev/hwrng0
> + is proving access to first available HWRNG. To examine this source you can use:
s/is providing/provides
> +.. code-block:: sh
> +
> + md -s /dev/hwrng0
> +
> +- /dev/prng – is providing access to PRNG. To examine this source you can use:
s/is providing/provides
Yegor
> +.. code-block:: sh
> +
> + md -s /dev/prng
> +
> +To seed PRNG from user space the :ref:`command_seed` is provided.
> +For example:
> +.. code-block:: sh
> +
> + seed 12345
> + md -s /dev/prng
> +
> diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
> index 435649f353..791c8e0979 100644
> --- a/Documentation/user/user-manual.rst
> +++ b/Documentation/user/user-manual.rst
> @@ -33,6 +33,7 @@ Contents:
> reset-reason
> system-reset
> state
> + random
>
> * :ref:`search`
> * :ref:`genindex`
> --
> 2.11.0
>
>
>
> _______________________________________________
> barebox mailing list
> barebox@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox
>
_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox
^ permalink raw reply [flat|nested] only message in thread