Difference between revisions of "Hardware random overview"

[quality revision] [quality revision]
m (How to use the framework)
 
m (Cleanup)
Template:ArticleMainWriter Template:ArticleApprovedVersion SUMMARY
This article gives information about the hardware random (HWRNG) framework.

1 Article Purpose[edit]

This article gives information about the hardware random (HWRNG) framework.

2 Framework purpose[edit]

The Hardware random framework is integrated in the kernel. It provides access to RNG peripherals and focuses on supporting the hardware number generator.

2 3 System overview[edit]

The HW random framework allows retrieving random numbers in userland.

Alternate text
Hw Random

23.1 Component description[edit]

  • HW random core (Kernel space)

Generic interface in kernel space. This layer is in charge of creating the character device (char device) and sysfs to access hw_random.

  • RNG (Kernel space)

Hardware random Linux® drivers handling the HW blocks.

  • RNG (Hardware)

HW blocks handling the RNG peripheral.

23.2 API description[edit]

The Hardware random framework uses char device API[1] ioctl operations. For additional information, refer to:

  • sysfs interface.
  • Kernel Documentation directory[2]

3 4 Configuration[edit]

34.1 Kernel configuration[edit]

The Hardware random support is activated by default in ST deliveries. No specific configuration is required apart from enabling or disabling peripheral support using Linux® Menuconfig tool. Refer to Menuconfig or how to configure kernel and select:

  [*] Device Drivers --->
    [*] Character devices --->
      [*] Hardware Random Number Generator Core support --->
        [*] STMicroelectronics STM32 random number generator

34.2 Device tree configuration[edit]

DT configuration can be done thanks to the STM32CubeMX.

A detailed device tree configuration is described in RNG device tree configuration.

4 5 How to use the framework[edit]

The framework provides external interfaces from userland : How to control RNG.

45.1 How to use from char device[edit]

The community tool for using Hardware random framework is rng_tools[3] which provides a complete set of utilities related to random number generators:

  • rngd: runs a background daemon that opens /dev/hwrng file (default) to connect and retrieve random numbers.
  • rngtest: runs different tests that check the entropy and verify the compliance regarding FIPS 140-2 standard.

45.2 How to use from sysfs[edit]

Available devices compatible with Hardware framework can be listed using sysfs commands:

 
Board $> cat /sys/class/misc/hw_random/rng_available
 stm32-rng

The selected device is shown here:

 
Board $> cat /sys/class/misc/hw_random/rng_current
 stm32-rng

To select a different device:

 
Board $> echo "stm32-rng"> /sys/class/misc/hw_random/rng_current

5 6 How to trace and debug the framework[edit]

Light information on the framework can be accessed by using sysfs.

By default, the framework does not provide any specific debug output or dynamic debugging tool.

6 7 Source code location[edit]

Hardware random drivers and framework are available here[4].

7 8 To go further[edit]

Code examples are directly available from rng-tools[3] github.

8 9 References[edit]



<noinclude>

{{ArticleBasedOnModel | [[Framework overview article model]]}}
{{ArticleMainWriter | LionelD}}
{{ArticleApprovedVersion | LionelD | FabienD(Passed, 25Jun'18) | No previous approved version | AnneJ - 24Oct'18 - 9410| 29Oct'18}}

[[Category:Security]]</noinclude>


'''SUMMARY '''<br>
==Article Purpose==This article gives information about the hardware random (HWRNG) framework.

==Framework purpose==
The Hardware random framework is integrated in the kernel. It provides access to RNG peripherals and focuses on supporting the hardware number generator.

==System overview==
The HW random framework allows retrieving random numbers in userland.

[[File:hwrngapi.png|thumb|center|766px|link=|alt=Alternate text|Hw Random]]

===Component description===
* '''HW random core''' (Kernel space) <br>

Generic interface in kernel space. This layer is in charge of creating the character device (char device) and sysfs to access hw_random.

* '''RNG''' (Kernel space)
Hardware random Linux<sup>&reg;</sup> drivers handling the HW blocks.

* '''RNG''' (Hardware)
HW blocks handling the RNG peripheral.

===API description===
The Hardware random framework uses char device API<ref>https://bootlin.com/doc/legacy/accessing-hardware/accessing-hardware.pdf</ref> ioctl operations.
For additional information, refer to:
* sysfs interface.
* Kernel Documentation directory<ref>{{CodeSource | Linux kernel | Documentation/hw_random.txt}}</ref>


==Configuration==
===Kernel configuration===
The Hardware random support is activated by default in ST deliveries. No specific configuration is required apart from enabling or disabling peripheral support using Linux<sup>&reg;</sup> Menuconfig tool. Refer to [[Menuconfig or how to configure kernel | Menuconfig or how to configure kernel ]] and select:<pre>

  [*] Device Drivers --->
    [*] Character devices --->
      [*] Hardware Random Number Generator Core support --->
        [*] STMicroelectronics STM32 random number generator</pre>


===Device tree configuration===
DT configuration can be done thanks to the [[STM32CubeMX]].

A detailed device tree configuration is described in [[RNG device tree configuration]].

== How to use the framework ==
The framework provides external interfaces from userland : [[How_to_control_a_RNG_in_userspace|How to control RNG]].

=== How to use from char device ===
The community tool for using Hardware random framework is rng_tools<ref name=rngtools>[https://git.kernel.org/pub/scm/utils/kernel/rng-tools/rng-tools.git/ Rng_tools source code]</ref> which provides a complete set of utilities related to random number generators:

* '''rngd''': runs a background daemon that opens /dev/hwrng file (default) to connect and retrieve random numbers.
* '''rngtest''': runs different tests that check the entropy and verify the compliance regarding FIPS 140-2 standard.

=== How to use from sysfs ===
Available devices compatible with Hardware framework can be listed using sysfs commands:

  {{Board$}} cat /sys/class/misc/hw_random/rng_available
  '''stm32-rng'''

The selected device is shown here:
  {{Board$}} cat /sys/class/misc/hw_random/rng_current
  '''stm32-rng'''

To select a different device:
  {{Board$}} echo "stm32-rng"> /sys/class/misc/hw_random/rng_current

==How to trace and debug the framework==
Light information on the framework can be accessed by using [[#How_to_use_from_sysfs|sysfs]].

By default, the framework does not provide any specific debug output or dynamic debugging tool.

==Source code location==
Hardware random drivers and framework are available here<ref>{{CodeSource | Linux kernel | drivers/char/hw_random}}, Hw_random sources</ref>.

==To go further==
Code examples are directly available from rng-tools<ref name=rngtools/> github.

==References==
<references />

<noinclude>

{{ArticleBasedOnModel | [[Framework overview article model]]}}
{{PublicationRequestId | 9410 | 2018-10-24 | AnneJ}}
[[Category:Security]]</noinclude>
Line 1: Line 1:
<noinclude>
+
==Article Purpose==
{{ArticleBasedOnModel | [[Framework overview article model]]}}
 
{{ArticleMainWriter | LionelD}}
 
{{ArticleApprovedVersion | LionelD | FabienD(Passed, 25Jun'18) | No previous approved version | AnneJ - 24Oct'18 - 9410| 29Oct'18}}
 
 
 
[[Category:Security]]
 
</noinclude>
 
 
 
'''SUMMARY '''<br>
 
 
This article gives information about the hardware random (HWRNG) framework.
 
This article gives information about the hardware random (HWRNG) framework.
   
Line 85: Line 77:
   
 
<references />
 
<references />
  +
  +
<noinclude>
  +
{{ArticleBasedOnModel | [[Framework overview article model]]}}
  +
{{PublicationRequestId | 9410 | 2018-10-24 | AnneJ}}
  +
[[Category:Security]]
  +
</noinclude>

Attachments

Discussions