[PATCH v1] Documentation: random: provide documentation.

[Yegor Yefremov]

Hi Oleksij,

On Mon, May 8, 2017 at 2:32 PM, Oleksij Rempel <o.rempel at pengutronix.de> wrote:
> Signed-off-by: Oleksij Rempel <o.rempel at 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 at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox
>