diff options
author | Oleksij Rempel <o.rempel@pengutronix.de> | 2017-05-09 07:34:04 +0200 |
---|---|---|
committer | Sascha Hauer <s.hauer@pengutronix.de> | 2017-05-11 08:18:12 +0200 |
commit | cf4c8c921e13d6d08c7869048186d6ac0996d58b (patch) | |
tree | 58e9b43c69346386a0d6b014b6f091c728fd4156 /Documentation | |
parent | 0bed8c578c8df18353495cde574b622e70fbcee5 (diff) | |
download | barebox-cf4c8c921e13d6d08c7869048186d6ac0996d58b.tar.gz barebox-cf4c8c921e13d6d08c7869048186d6ac0996d58b.tar.xz |
Documentation: provide documentation for RNG interfaces.
Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/user/random.rst | 63 | ||||
-rw-r--r-- | Documentation/user/user-manual.rst | 1 |
2 files changed, 64 insertions, 0 deletions
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` |