[PATCH v3] Documentation: provide documentation for RNG interfaces.

[Sascha Hauer]

On Tue, May 09, 2017 at 07:34:04AM +0200, Oleksij Rempel wrote:
> Signed-off-by: Oleksij Rempel <o.rempel at pengutronix.de>
> ---
>  Documentation/user/random.rst      | 63 ++++++++++++++++++++++++++++++++++++++
>  Documentation/user/user-manual.rst |  1 +
>  2 files changed, 64 insertions(+)
>  create mode 100644 Documentation/user/random.rst

Applied, thanks

Sascha

> 
> diff --git a/Documentation/user/random.rst b/Documentation/user/random.rst
> new file mode 100644
> index 0000000000..95dad72e55
> --- /dev/null
> +++ b/Documentation/user/random.rst
> @@ -0,0 +1,63 @@
> +Random Number Generator support
> +===============================
> +
> +Barebox provides two types of RNG sources - PRNG and HWRNG:
> +
> +- "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 a message “error: no HWRNG available!”
> +         * 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
> +  provides access to first available HWRNG. To examine this source you can use:
> +
> +.. code-block:: sh
> +
> +  md -s /dev/hwrng0
> +
> +- /dev/prng
> +  provides access to PRNG. To examine this source you can use:
> +
> +.. 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

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |