From f3da26090d22a3362aa0049cad537fa33e434ae5 Mon Sep 17 00:00:00 2001 From: Toufic Date: Wed, 8 Apr 2026 12:11:53 +0200 Subject: [PATCH 1/2] open source changes --- .github/ISSUE_TEMPLATE/bug_report.md | 23 +++++++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 26 ++++++++++ .github/pull_request_template.md | 13 +++++ .github/workflows/rust-vuln-scan.yml | 26 ++++++++++ .github/workflows/rust.yml | 22 +++++++++ CODE_OF_CONDUCT.md | 56 ++++++++++++++++++++++ CONTEXT.md | 34 +++++++++++++ CONTRIBUTING.md | 26 ++++++++++ Cargo.toml | 8 +++- LICENSE | 21 ++++++++ README.md | 12 ++++- examples/chacha_practrand.rs | 2 +- examples/chacha_testu01.rs | 4 +- tests/practrand_test.rs | 2 +- tests/testu01_test.rs | 2 +- 16 files changed, 270 insertions(+), 8 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/rust-vuln-scan.yml create mode 100644 .github/workflows/rust.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTEXT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..24585e8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,23 @@ +--- +name: Bug Report +about: Report a bug in the project +title: "[BUG] " +labels: bug +assignees: "" +--- + +### Description +Describe the unexpected behavior. + +### Steps to Reproduce +1. ... +2. ... +3. ... + +### Expected Behavior +Describe what you expected to happen. + +### Environment +- OS: +- Rust version: +- Crate version: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..ec4bb38 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..ece0830 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,26 @@ +name: Feature Request +description: Suggest a new feature or improvement +title: "[Feature] " +labels: ["enhancement"] +body: + - type: textarea + id: motivation + attributes: + label: Motivation + description: What problem do you want to solve? + placeholder: Explain why this feature would be useful. + validations: + required: true + - type: textarea + id: solution + attributes: + label: Proposed Solution + placeholder: Describe your idea or implementation approach. + - type: checkboxes + id: impact + attributes: + label: Impact + options: + - label: Changes public API + - label: Requires new tests + - label: Affects documentation diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..33486af --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,13 @@ +## Description +Briefly describe what this PR does and why it’s needed. + +## Changes +- [ ] Main feature or fix implemented +- [ ] Tests added +- [ ] Documentation updated + +## Checklist +- [ ] Code compiles without warnings +- [ ] All tests pass (`cargo test`) +- [ ] Commit messages are clear and descriptive +- [ ] PR linked to an issue if applicable (`Fixes #XX`) diff --git a/.github/workflows/rust-vuln-scan.yml b/.github/workflows/rust-vuln-scan.yml new file mode 100644 index 0000000..3a643a5 --- /dev/null +++ b/.github/workflows/rust-vuln-scan.yml @@ -0,0 +1,26 @@ +name: Rust Vulnerability Scan + +on: + push: + branches: [ "main" ] + pull_request: + paths: + - '**/Cargo.toml' + - '**/Cargo.lock' + # schedule: + # # Run daily at midnight to catch newly disclosed vulnerabilities + # - cron: '0 0 * * *' + +jobs: + audit: + name: Run cargo-audit + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install cargo-audit + uses: taiki-e/install-action@cargo-audit + + - name: Run cargo-audit + run: cargo audit \ No newline at end of file diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml new file mode 100644 index 0000000..9fd45e0 --- /dev/null +++ b/.github/workflows/rust.yml @@ -0,0 +1,22 @@ +name: Rust + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +env: + CARGO_TERM_COLOR: always + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Build + run: cargo build --verbose + - name: Run tests + run: cargo test --verbose diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..90d99c2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,56 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, codes, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies to all project spaces and events, including issue trackers, pull requests, mailing lists, chat channels, video calls, in-person events, and any other project-related communications. + +## Reporting + +To report an incident, contact the project conduct team at [conduct@spacecomputer.io](mailto:conduct@spacecomputer.io) or reach out to any maintainer. If you prefer, you may submit an anonymous report via a form or third-party service (link/placeholders should be added). Please include as much detail as possible, including links, timestamps, and any relevant context. + +## Confidentiality and Anonymity + +Reports will be handled confidentially. Reporters may request anonymity; the conduct team will make reasonable efforts to protect identities and sensitive information when requested. + +## Consequences + +Consequences for violations may include private warnings, required remediation (for example, apologies or training), temporary suspension of repository or event access, removal of privileges, or permanent bans. The chosen action will be proportional to the severity and frequency of the behavior. + +## Anti-Retaliation + +Retaliation against anyone who reports misconduct or participates in an investigation is strictly prohibited and will itself be treated as a serious violation of this Code of Conduct. + +## Conflict of Interest & Recusal + +If a conduct team member has a conflict of interest in a case, they will recuse themselves and another impartial member will handle the investigation. + +## Contact & Upkeep + +For questions about this policy or to update contact details, contact [conduct@spacecomputer.io](mailto:conduct@spacecomputer.io). + +This policy was last updated: 2026-03-28 \ No newline at end of file diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..f859fcf --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,34 @@ +# Project Context + +Rust library providing bindings for two statistical RNG test suites: **TestU01** and **PractRand**. Any type implementing `RngCore` can be tested. + +## Architecture + +- `src/lib.rs` — Re-exports `testu01` and `practrand` modules behind cfg flags +- `src/testu01.rs` — FFI bindings to the C TestU01 library. Uses a global `Mutex>` to bridge Rust's `RngCore` trait to TestU01's C callback (`extern "C" fn`). Bindings are auto-generated by `bindgen` +- `src/practrand.rs` — Spawns the `RNG_test` binary as a subprocess, pipes random bytes to its stdin, and parses the exit code. No FFI involved +- `build.rs` — Downloads, compiles, and installs both TestU01 (C, autotools) and PractRand (C++, manual g++ compilation) into `vendor/`. Sets cfg flags `has_testu01_bindings` and `has_practrand` + +## Build + +The build script automatically downloads and compiles the C/C++ dependencies on first build. Requires: Rust toolchain, C/C++ compiler (gcc/g++), `make`, `curl`, `tar`, `unzip`. + +```bash +cargo build # downloads + compiles vendored C/C++ deps on first run +cargo test # runs smoke tests (SmallCrush for TestU01, 1MB for PractRand) +``` + +The `vendor/` directory is gitignored — it's created at build time, not checked in. + +## Key design decisions + +- **TestU01 uses FFI** because it needs a C function pointer callback to pull random data. The global mutex is required because TestU01's callback signature has no user-data parameter +- **PractRand uses subprocess** because it's simpler — the `RNG_test` tool reads from stdin, so we just pipe bytes to it +- **Conditional compilation** (`#[cfg(has_testu01_bindings)]` / `#[cfg(has_practrand)]`) — modules are only available when their C/C++ deps compiled successfully + +## Tests + +- `tests/testu01_test.rs` — Runs SmallCrush on `OsRng` +- `tests/practrand_test.rs` — Runs PractRand on `ChaCha20Rng` with 1MB of data + +Tests are slow (SmallCrush takes ~30s, PractRand is faster at small sizes). Both are gated behind cfg flags. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..149e6a7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,26 @@ +# Contributing to statistical-verification + +We welcome contributions to statistical-verification! Whether it's fixing a bug, adding a new feature, improving documentation, or suggesting new ideas, your contributions are highly appreciated. + +## How to Contribute + +1. **Fork the Repository**: Start by forking the statistical-verification repository to your GitHub account. +2. **Create a Branch**: Create a new branch for your contribution. Use a descriptive name for the branch, such as `fix-issue-123` or `add-new-feature`. Only lowercase letters, numbers, and hyphens are allowed in branch names. +3. **Make Your Changes**: Make the necessary changes in your branch. Ensure that your code follows the project's coding standards and includes appropriate tests if applicable. +4. **Commit Your Changes**: Commit your changes with a clear and concise commit message that describes the purpose of the change. +5. **Push to GitHub**: Push your branch to your forked repository on GitHub. +6. **Create a Pull Request**: Go to the original statistical-verification repository and create a pull request from your branch. Provide a detailed description of your changes and why they are necessary. +7. **Review Process**: The maintainers will review your pull request and may request changes or provide feedback. Be responsive to any comments and make the necessary adjustments. +8. **Merge**: Once your pull request is approved, it will be merged into the main branch. + +## Code of Conduct + +Please note that we have a [Code of Conduct](CODE_OF_CONDUCT.md) in place to ensure a welcoming and inclusive environment for all contributors. By participating in this project, you agree to abide by its terms. + +## Reporting Issues + +If you encounter any issues or have suggestions for improvements, please feel free to open an issue in the GitHub repository. Provide as much detail as possible to help us understand and address the problem effectively. + +--- + +Thank you for your interest in contributing to statistical-verification! We look forward to your contributions and working together to make statistical-verification even better. \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml index 7831330..f027783 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,13 @@ [package] -name = "rng-statistical-tests" +name = "statistical-verification" version = "0.1.0" edition = "2021" +description = "Rust bindings for statistical testing of RNGs using TestU01 and PractRand" +license = "MIT" +repository = "https://github.com/spacecomputer-io/statistical-verification" +homepage = "https://docs.spacecomputer.io" +keywords = ["cryptography", "random", "verification", "entropy", "rng"] +categories = ["cryptography"] build = "build.rs" [dependencies] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..25dff4d --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 SpaceComputer + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 4e776f7..56c3e3d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,12 @@ -# rng-statistical-tests +# SpaceComputer | statistical-verification + +![spacecomputer logo](https://raw.githubusercontent.com/spacecomputer-io/media-kit/refs/heads/main/SpaceComputer/logo/SpaceComputer_banner.png) + +![Tests](https://github.com/spacecomputer-io/statistical-verification/actions/workflows/rust.yml/badge.svg?branch=main) + +This repository contains the statistical-verification project by SpaceComputer. + +# statistical-verification A Rust library for statistical testing of random number generators. Test any `RngCore` implementation with TestU01 (SmallCrush, Crush, BigCrush) or PractRand test suites. @@ -8,7 +16,7 @@ Add to your `Cargo.toml`: ```toml [dependencies] -rng-statistical-tests = { git = "https://github.com/spacecomputer-io/statistical-verification.git" } +statistical-verification = { git = "https://github.com/spacecomputer-io/statistical-verification.git" } ``` TestU01 and PractRand are automatically downloaded and built during compilation. diff --git a/examples/chacha_practrand.rs b/examples/chacha_practrand.rs index 47450a4..1b5b1d4 100644 --- a/examples/chacha_practrand.rs +++ b/examples/chacha_practrand.rs @@ -1,6 +1,6 @@ use rand_chacha::ChaCha20Rng; use rand_core::SeedableRng; -use rng_statistical_tests::practrand::{run_test, Config}; +use statistical_verification::practrand::{run_test, Config}; fn main() { let seed = [0u8; 32]; diff --git a/examples/chacha_testu01.rs b/examples/chacha_testu01.rs index 8c74801..e32b382 100644 --- a/examples/chacha_testu01.rs +++ b/examples/chacha_testu01.rs @@ -1,7 +1,7 @@ use rand_chacha::ChaCha20Rng; use rand_core::SeedableRng; -use rng_statistical_tests::testu01::{bbattery_BigCrush, bbattery_Crush, bbattery_SmallCrush}; -use rng_statistical_tests::testu01::{delete_unif01_gen, make_unif01_gen, register_rng}; +use statistical_verification::testu01::{bbattery_BigCrush, bbattery_Crush, bbattery_SmallCrush}; +use statistical_verification::testu01::{delete_unif01_gen, make_unif01_gen, register_rng}; fn main() { let seed = [0u8; 32]; diff --git a/tests/practrand_test.rs b/tests/practrand_test.rs index 153fc46..6c38884 100644 --- a/tests/practrand_test.rs +++ b/tests/practrand_test.rs @@ -2,7 +2,7 @@ use rand_chacha::ChaCha20Rng; use rand_core::SeedableRng; -use rng_statistical_tests::practrand::{run_test, Config}; +use statistical_verification::practrand::{run_test, Config}; #[test] fn practrand_smoke_test_chacha20() { diff --git a/tests/testu01_test.rs b/tests/testu01_test.rs index f78e702..37e2ed3 100644 --- a/tests/testu01_test.rs +++ b/tests/testu01_test.rs @@ -1,7 +1,7 @@ #![cfg(has_testu01_bindings)] use rand::rngs::OsRng; -use rng_statistical_tests::testu01::{ +use statistical_verification::testu01::{ bbattery_SmallCrush, delete_unif01_gen, make_unif01_gen, register_rng, }; From 9203da6b0bab6ea8b244057b8c14413675185424 Mon Sep 17 00:00:00 2001 From: Toufic Date: Thu, 9 Apr 2026 17:05:40 +0200 Subject: [PATCH 2/2] update context --- CONTEXT.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index f859fcf..ba0a1b1 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -2,6 +2,31 @@ Rust library providing bindings for two statistical RNG test suites: **TestU01** and **PractRand**. Any type implementing `RngCore` can be tested. +## Background + +Statistical test suites check if an RNG's output looks like true randomness. They run batteries of hypothesis tests, each looking for a specific pattern or correlation that a weak generator might produce. A generator that passes these suites isn't proven secure, but one that fails them is considered broken. + +### TestU01 + +TestU01 is a C library by Pierre L'Ecuyer and Richard Simard (Université de Montréal, 2007). It's the most widely cited academic framework for empirical RNG testing. Three predefined batteries, in increasing order of rigor: + +- **SmallCrush**: 10 tests, runs in seconds. Quick sanity check. +- **Crush**: 96 tests, ~1 hour. Catches most common generator weaknesses. +- **BigCrush**: 106 tests, several hours. The standard academic benchmark for generator quality. + +Each test produces a p-value. Values outside [0.001, 0.999] are flagged suspect; values outside [1e-10, 1 - 1e-10] are outright failures. TestU01 requires a C function-pointer callback to pull random bits, which is why this crate uses FFI with a global mutex to bridge Rust's `RngCore` trait. + +### PractRand + +PractRand (Practically Random) is a C++ toolkit by Chris Doty-Humphrey. Unlike TestU01's fixed batteries, PractRand reads a byte stream from stdin and runs tests at geometrically increasing data thresholds (256KB, 512KB, 1MB, 2MB, ...). This makes it good for open-ended testing: a generator that passes at 1GB may fail at 16TB. + +PractRand is particularly good at catching short-range correlations and low-bit weaknesses. Key config knobs: + +- **-tf (folding)**: 0 = raw data only; 1 (default) = also tests a transform emphasizing low bits; 2 = wider variety of transforms. +- **-te (expanded)**: 0 (default) = core tests, optimized for sensitivity per time; 1 = expanded set, optimized per byte consumed. + +Since PractRand's `RNG_test` reads from stdin, this crate just spawns it as a subprocess and pipes bytes to it. No FFI needed. + ## Architecture - `src/lib.rs` — Re-exports `testu01` and `practrand` modules behind cfg flags