1.. _random_api:
2
3Random Number Generation
4########################
5
6The random API subsystem provides random number generation APIs in both
7cryptographically and non-cryptographically secure instances. Which
8random API to use is based on the cryptographic requirements of the
9random number. The non-cryptographic APIs will return random values
10much faster if non-cryptographic values are needed.
11
12The cryptographically secure random functions shall be compliant to the
13FIPS 140-2 [NIST02]_ recommended algorithms. Hardware based random-number
14generators (RNG) can be used on platforms with appropriate hardware support.
15Platforms without hardware RNG support shall use the `CTR-DRBG algorithm
16<https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf>`_.
17The algorithm can be provided by `TinyCrypt <https://01.org/tinycrypt>`_
18or `mbedTLS <https://tls.mbed.org/ctr-drbg-source-code>`_ depending on
19your application performance and resource requirements.
20
21  .. note::
22
23    The CTR-DRBG generator needs an entropy source to establish and
24    maintain the cryptographic security of the PRNG.
25
26.. _random_kconfig:
27
28Kconfig Options
29***************
30
31These options can be found in the following path :zephyr_file:`subsys/random/Kconfig`.
32
33:kconfig:option:`CONFIG_TEST_RANDOM_GENERATOR`
34 For testing, this option allows a non-random number generator to be used and
35 permits random number APIs to return values that are not truly random.
36
37The random number generator choice group allows selection of the RNG
38source function for the system via the RNG_GENERATOR_CHOICE choice group.
39An override of the default value can be specified in the SOC or board
40.defconfig file by using:
41
42.. code-block:: none
43
44   choice RNG_GENERATOR_CHOICE
45	   default XOSHIRO_RANDOM_GENERATOR
46   endchoice
47
48The random number generators available include:
49
50:kconfig:option:`CONFIG_TIMER_RANDOM_GENERATOR`
51 enables number generator based on system timer clock. This number
52 generator is not random and used for testing only.
53
54:kconfig:option:`CONFIG_ENTROPY_DEVICE_RANDOM_GENERATOR`
55 enables a random number generator that uses the enabled hardware
56 entropy gathering driver to generate random numbers.
57
58:kconfig:option:`CONFIG_XOSHIRO_RANDOM_GENERATOR`
59 enables the Xoshiro128++ pseudo-random number generator, that uses the
60 entropy driver as a seed source.
61
62The CSPRNG_GENERATOR_CHOICE choice group provides selection of the
63cryptographically secure random number generator source function. An
64override of the default value can be specified in the SOC or board
65.defconfig file by using:
66
67.. code-block:: none
68
69   choice CSPRNG_GENERATOR_CHOICE
70	   default CTR_DRBG_CSPRNG_GENERATOR
71   endchoice
72
73The cryptographically secure random number generators available include:
74
75:kconfig:option:`CONFIG_HARDWARE_DEVICE_CS_GENERATOR`
76 enables a cryptographically secure random number generator using the
77 hardware random generator driver
78
79:kconfig:option:`CONFIG_CTR_DRBG_CSPRNG_GENERATOR`
80 enables the CTR-DRBG pseudo-random number generator. The CTR-DRBG is
81 a FIPS140-2 recommended cryptographically secure random number generator.
82
83Personalization data can be provided in addition to the entropy source
84to make the initialization of the CTR-DRBG as unique as possible.
85
86:kconfig:option:`CONFIG_CS_CTR_DRBG_PERSONALIZATION`
87 CTR-DRBG Initialization Personalization string
88
89API Reference
90*************
91
92.. doxygengroup:: random_api
93