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>`_.
17
18The algorithm can be provided by  `mbedTLS <https://tls.mbed.org/ctr-drbg-source-code>`_.
19
20  .. note::
21
22    The CTR-DRBG generator needs an entropy source to establish and
23    maintain the cryptographic security of the PRNG.
24
25.. _random_kconfig:
26
27Kconfig Options
28***************
29
30These options can be found in the following path :zephyr_file:`subsys/random/Kconfig`.
31
32:kconfig:option:`CONFIG_TEST_RANDOM_GENERATOR`
33 For testing, this option allows a non-random number generator to be used and
34 permits random number APIs to return values that are not truly random.
35
36The random number generator choice group allows selection of the RNG
37source function for the system via the RNG_GENERATOR_CHOICE choice group.
38An override of the default value can be specified in the SOC or board
39.defconfig file by using:
40
41.. code-block:: none
42
43   choice RNG_GENERATOR_CHOICE
44	   default XOSHIRO_RANDOM_GENERATOR
45   endchoice
46
47The random number generators available include:
48
49:kconfig:option:`CONFIG_TIMER_RANDOM_GENERATOR`
50 enables number generator based on system timer clock. This number
51 generator is not random and used for testing only.
52
53:kconfig:option:`CONFIG_ENTROPY_DEVICE_RANDOM_GENERATOR`
54 enables a random number generator that uses the enabled hardware
55 entropy gathering driver to generate random numbers.
56
57:kconfig:option:`CONFIG_XOSHIRO_RANDOM_GENERATOR`
58 enables the Xoshiro128++ pseudo-random number generator, that uses the
59 entropy driver as a seed source.
60
61The CSPRNG_GENERATOR_CHOICE choice group provides selection of the
62cryptographically secure random number generator source function. An
63override of the default value can be specified in the SOC or board
64.defconfig file by using:
65
66.. code-block:: none
67
68   choice CSPRNG_GENERATOR_CHOICE
69	   default CTR_DRBG_CSPRNG_GENERATOR
70   endchoice
71
72The cryptographically secure random number generators available include:
73
74:kconfig:option:`CONFIG_HARDWARE_DEVICE_CS_GENERATOR`
75 enables a cryptographically secure random number generator using the
76 hardware random generator driver
77
78:kconfig:option:`CONFIG_CTR_DRBG_CSPRNG_GENERATOR`
79 enables the CTR-DRBG pseudo-random number generator. The CTR-DRBG is
80 a FIPS140-2 recommended cryptographically secure random number generator.
81
82Personalization data can be provided in addition to the entropy source
83to make the initialization of the CTR-DRBG as unique as possible.
84
85:kconfig:option:`CONFIG_CS_CTR_DRBG_PERSONALIZATION`
86 CTR-DRBG Initialization Personalization string
87
88API Reference
89*************
90
91.. doxygengroup:: random_api
92