Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/microcontroleurmonde/rp2040-rng

A Micro-python library that provides an interface to generate a random number using the hardware RNG principle of the ESP32. It takes a measurement on one of the RP2040's ADC channels to improve the entropy noise and generate a random number.
https://github.com/microcontroleurmonde/rp2040-rng

micropython rng rp2040

Last synced: 1 day ago
JSON representation

A Micro-python library that provides an interface to generate a random number using the hardware RNG principle of the ESP32. It takes a measurement on one of the RP2040's ADC channels to improve the entropy noise and generate a random number.

Awesome Lists containing this project

README 

        
# RP2040 True Random Number Generator (TRNG)



### Breakdown of Sections



1. **Project Description**: Generation of random numbers using the RP2040 and various entropy sources.

2. **Features**: Lists the main features of the project, such as the use of ADC for entropy, SHA-256 whitening, and the use of RTC for additional randomness.

3. **Requirements**: Specifies what hardware and software are needed.

4. **Installation**: Provides steps for cloning the repository and uploading the files to the RP2040.

5. **Usage**: Details how to use the library and run the example script (generate_random.py).

6. **How it Works**: Explains the steps involved in generating random numbers and how entropy is collected, mixed, and whitened.

7. **Testing Randomness**: Mentions statistical tests that can be used to evaluate the quality of randomness.

8. **Diehard Test for Validation**:  Test reliably and validation.

9. **Acknowledgements**: Credits any technologies or libraries used in the project.

10. **Disclaimer**



## Project Description



This project implements a **True Random Number Generator (TRNG)** using the **RP2040** microcontroller. The generator collects entropy from an **ADC** (Analog-to-Digital Converter) and mixes it with a **SHA-256** hashing function to produce high-quality random numbers. The randomness is further enhanced by using the **RP2040's RTC (Real-Time Clock)** for time-based entropy.



## Features



- **ADC-based entropy**: Collects noise-based entropy using the RP2040's ADC (GPIO 28).

- **Entropy mixing**: Uses XOR and Linear Congruential Generator (LCG) techniques for mixing the entropy.

- **SHA-256 whitening**: Applies the **SHA-256** hash function to whiten the entropy and reduce correlations.

- **Real-Time Clock (RTC)**: Uses the RP2040's RTC to add time-based entropy for further randomness.

- **Counter-based variability**: Introduces additional variability using an internal counter.



## Requirements



- **RP2040-based microcontroller**.

- **MicroPython** firmware installed on the board.

- **`machine`**, **`utime`**, and **`hashlib`** libraries (built-in with MicroPython).



## Installation



### 1. Clone the repository



- git clone https://github.com/MicroControleurMonde/RP2040-RNG/rp2040-trng.git

- cd rp2040-trng



### 2. Upload the files to your RP2040 board

Upload the following Python files to your RP2040 board:



- rp2040_rng_lib.py

- generate_random.py



### 3. Run the script

Once the files are uploaded, you can run the 'generate_random.py' script to start generating random numbers.



## Usage

#### 1. rp2040_rng_lib.py – Library for generating random numbers

This Python library provides a class ***RandomGenerator*** that generates random numbers based on the RP2040's ADC and a SHA-256 whitening process.



#### 2. generate_random.py – Example script

This script imports the RandomGenerator class from ***rp2040_rng_lib.py*** and generates one random number at a time.



#### Output Example:



Generated random number: 4779610172586853948



## How it Works



### 1. Entropy Collection

The generator uses the ADC to read random noise or fluctuating signals, providing a source of entropy.



### 2. Entropy Mixing

The collected entropy is mixed using XOR operations and a Linear Congruential Generator (LCG) to enhance randomness.



### 3. Whitening

The entropy is passed through a SHA-256 hash function to ensure it is unpredictable and unbiased.



### 4. Time-based Entropy

The current Unix timestamp from the RP2040's RTC is used to further whiten the entropy.



### 5. Output

The final output is a 64-bit random number that is periodically generated and can be used in applications requiring randomness.



## Testing Randomness



To ensure the quality of the random numbers, you can use statistical randomness tests such as:



- **Diehard Tests**

[Dieharder: A Random Number Test Suite Version 3.31.1] (https://webhome.phy.duke.edu/~rgb/General/dieharder.php)

- **NIST Statistical Test Suite**



These tests will help evaluate the strength of the randomness generated by this code.



## Diehard Test for Validation



To perform a Diehard test reliably and validate the random number generator for RP2040, it is recommended to generate a sample of at least several million bits.



For example, for a sample of 10 million bits, you will need to generate approximately **156,250** 64-bit numbers.



- Diehard test results (over 200,000 values) can be found in the file **'diehard_sample_report.txt '**.

- General results comments  in the file **'diehard_sample_report.md '**.



### Number of bits needed

To generate 1 million bits, you will need to generate about:



$$

\frac{10^{6} \, \text{bits}}{64 \, \text{bits by number}} \approx 15625 \, \text{64-bit numbers}

$$



## Acknowledgements



The project is based on the **RP2040 microcontroller**, and its **MicroPython firmware**.  

The entropy whitening is done using the **SHA-256 algorithm** from the **hashlib** library.



Tested on an original Raspberry Pi Pico, a XIAO seed studio RP2040 and a Waveshare RP2040-Plus. 

The code works perfectly on all three platforms, regardless of the ADC channel used. 



## Disclaimer



The code contained in this repository is provided “as is”, without any warranty of performance, accuracy or result. The author shall not be liable for any direct or indirect damages that may result from the use of this code, including, but not limited to, loss of data or interruption of service.



Use of this code is entirely at your own risk. Please ensure that you fully understand the code before using it in a production environment or integrating it into your projects.