From b50cc3ac3a826a9d8302f5273ed0be6e159923a3 Mon Sep 17 00:00:00 2001 From: Toufic Date: Wed, 8 Apr 2026 12:12:04 +0200 Subject: [PATCH 1/2] open source changes --- CODE_OF_CONDUCT.md | 56 +++++++++++++++++ CONTEXT.md | 13 ++-- CONTRIBUTING.md | 26 ++++++++ Cargo.lock | 4 +- Cargo.toml | 9 ++- LICENSE | 21 +++++++ README.md | 31 +--------- overview.md | 146 --------------------------------------------- 8 files changed, 121 insertions(+), 185 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE delete mode 100644 overview.md 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 index ecc560b..d5e5858 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -39,9 +39,9 @@ RngCore / CryptoRng ← standard rand_core traits |------|------|------| | `RandomBlockSource` | `src/traits.rs` | Trait every entropy backend must implement | | `Ctrng` | `src/ctrng/mod.rs` | Public enum dispatching to concrete backends | -| `IpfsCtrng` | `src/ctrng/ipfs.rs` | IPFS beacon client (internal, behind `Ctrng`) | -| `IpfsConfig` | `src/ctrng/ipfs.rs` | Gateway list, `use_defaults`, timeout | -| `IpfsGateway` | `src/ctrng/ipfs.rs` | Newtype for gateway URL; builds `/ipfs/` and `/ipns/` paths | +| `IpfsBeacon` | `src/ctrng/ipfs_beacon.rs` | IPFS beacon client (internal, behind `Ctrng`) | +| `IpfsConfig` | `src/ctrng/ipfs_beacon.rs` | Gateway list, `use_defaults`, timeout | +| `IpfsGateway` | `src/ctrng/ipfs_beacon.rs` | Newtype for gateway URL; builds `/ipfs/` and `/ipns/` paths | | `CtrngBlock` | `src/ctrng/types.rs` | Block with sequence number, timestamp, 32-byte data | | `MixedCtrng` | `src/mixed.rs` | XOR of remote + local OS entropy | | `ReseedingRng` | `src/reseed.rs` | ChaCha20 DRBG with configurable reseed intervals | @@ -58,7 +58,7 @@ src/ ├── error.rs SourceError ├── ctrng/ │ ├── mod.rs Ctrng enum + RandomBlockSource impl -│ ├── ipfs.rs IpfsCtrng, IpfsGateway, IpfsConfig, DEFAULT_GATEWAYS +│ ├── ipfs_beacon.rs IpfsCtrng, IpfsGateway, IpfsConfig, DEFAULT_GATEWAYS │ └── types.rs BeaconResponse, CtrngBlock ├── mixed.rs MixedCtrng (XOR mixer) ├── reseed.rs ReseedingRng, ReseedConfig @@ -66,11 +66,12 @@ src/ └── local.rs LocalRng (OS entropy) tests/ -├── ipfs_live.rs live IPFS gateway tests (#[ignore]) +├── e2e_ipfs.rs live IPFS gateway tests +├── e2e_mixed.rs live MixedCtrng end-to-end tests ├── mixed_tests.rs MixedCtrng tests (some #[ignore]) ├── reseed_tests.rs ReseedingRng offline tests ├── rng_tests.rs BlockRng error propagation -└── statistical_tests.rs TestU01 / PractRand (behind features) +└── testu01_tests.rs TestU01 / PractRand (behind features) ``` ## Conventions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..57b6d46 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,26 @@ +# Contributing to crypto-ctrng + +We welcome contributions to crypto-ctrng! 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 crypto-ctrng 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 crypto-ctrng 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 crypto-ctrng! We look forward to your contributions and working together to make crypto-ctrng even better. \ No newline at end of file diff --git a/Cargo.lock b/Cargo.lock index 1beb529..084249d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -143,7 +143,7 @@ dependencies = [ "rand_chacha 0.3.1", "rand_core 0.6.4", "reqwest", - "rng-statistical-tests", + "statistical-verification", "serde", "serde_json", "sha2", @@ -910,7 +910,7 @@ dependencies = [ ] [[package]] -name = "rng-statistical-tests" +name = "statistical-verification" version = "0.1.0" source = "git+https://github.com/spacecomputer-io/statistical-verification.git#fd16ef0da4c74ed5e704e98a47d581e61a06ef71" dependencies = [ diff --git a/Cargo.toml b/Cargo.toml index b2877de..100f41c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,6 +2,13 @@ name = "crypto-ctrng" version = "0.1.0" edition = "2024" +rust-version = "1.85" +description = "Secure abstraction layer over a cosmic True Random Number Generator (cTRNG) backend, exposing RngCore/CryptoRng traits" +license = "MIT" +repository = "https://github.com/spacecomputer-io/crypto-ctrng" +homepage = "https://docs.spacecomputer.io" +keywords = ["cryptography", "random", "trng", "entropy", "rng"] +categories = ["cryptography"] [dependencies] rand_core = { version = "0.6", features = ["std"] } @@ -21,4 +28,4 @@ testu01 = [] practrand = [] [dev-dependencies] -rng-statistical-tests = { git = "https://github.com/spacecomputer-io/statistical-verification.git" } +statistical-verification = { git = "https://github.com/spacecomputer-io/statistical-verification.git" } 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 e0738bc..7e59c44 100644 --- a/README.md +++ b/README.md @@ -144,29 +144,9 @@ cargo test --test e2e_ipfs cargo test --test e2e_mixed ``` -You can also run the dedicated e2e integration targets individually: - -```bash -cargo test --test e2e_ipfs -cargo test --test e2e_mixed -``` - -To run the IPFS-backed end-to-end tests : - -```bash -cargo test test_e2e -``` - -You can also run the dedicated e2e integration targets individually: - -```bash -cargo test --test e2e_ipfs -cargo test --test e2e_mixed -``` - ### Statistical verification -Statistical testing is provided by the separate [`rng-statistical-tests`](https://github.com/spacecomputer-io/statistical-verification) library, which supports both **TestU01** and **PractRand**. +Statistical testing is provided by the separate [`statistical-verification`](https://github.com/spacecomputer-io/statistical-verification) library, which supports both **TestU01** and **PractRand**. TestU01 and PractRand are automatically downloaded and built during compilation - no manual setup required. @@ -176,12 +156,3 @@ To run statistical tests: cargo test --features testu01 # TestU01 SmallCrush cargo test --features practrand # PractRand (1 MiB) ``` - - -## License - -This project is licensed under the terms of the MIT License. See the [LICENSE](LICENSE) file for details. - -## Contributing - -We welcome contributions to this project! If you have suggestions for improvements or new features, please open an issue or submit a pull request. diff --git a/overview.md b/overview.md deleted file mode 100644 index 0412666..0000000 --- a/overview.md +++ /dev/null @@ -1,146 +0,0 @@ -**WARNING: This project is experimental and work-in-progress, use at your own risk!** - -## Overview - -This crate provides a lightweight and secure abstraction layer over a cosmic True Random Number Generator (cTRNG) backend. -It allows deterministic or hardware-backed randomness to be consumed through the standard `RngCore` and `CryptoRng` traits from `rand_core`. - -The main goals is to expose a clean, composable API for hardware or remote entropy backends. - -### Entropy ownership contract - -This crate's responsibility is to **verify** that the cTRNG backend provides unique blocks. The randomness flow is split between three layers: - -- **Gateway/back-end** (e.g. IPFS beacon, hardware TRNG) is responsible for generating unique 32-byte blocks with monotonic timestamps. This responsibility sits outside of this crate. -- **This crate** (`crypto-ctrng`) verifies uniqueness by enforcing timestamp monotonicity and rejecting duplicate blocks. -- **Application/client code** (e.g. TECDSA library) is responsible for personalizing the provided blocks to domain-separate pulls so a single user never receives the same derived value twice, even if they consume the same cTRNG block as other users (but this is something that we are looking to prevent in the future). - -**Note on entropy mixing:** -- `MixedCtrng` combines entropy sources (XOR of IPFS beacon + local OS randomness) for enhanced security, but still relies on the gateway for uniqueness guarantees. - -**Uniqueness guarantees:** -- This crate ensures that each `next_block()` call returns a block with a timestamp strictly greater than the previous one, preventing global block reuse. -- The calling library must personalize blocks per user/execution to prevent collisions between different users reading the same raw block. - -## Usage modes - -| Mode | Code | DRBG | Reseed | -|------|------|------|--------| -| Raw entropy | `BlockRng::new(source)` | N/A | N/A | -| Seeded DRBG (testing) | `ChaCha20Rng::from_seed(seed)` | ChaCha20 | N/A | -| DRBG + auto reseed | `ReseedingRng::new(source)` | ChaCha20 | 3200 bytes / 1 week | -| DRBG + prediction resistance | `ReseedingRng::with_prediction_resistance(source)` | ChaCha20 | every call | - -## Usage - -To use this crate, add it to your `Cargo.toml`: - -```toml -[dependencies] -crypto-ctrng = { git = "https://github.com/spacecomputer-io/crypto-ctrng.git", tag = "v0.1.0" } -``` - -### Fetch raw entropy (default gateways) - -```rust -use crypto_ctrng::{Ctrng, RandomBlockSource}; - -let beacon_key = "k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f"; - -let mut ctrng = Ctrng::ipfs(beacon_key, None); -let block = ctrng.next_block().expect("failed to fetch IPFS block"); -``` - -### Custom gateways with automatic fallback - -If a gateway is unresponsive or down, the next one in the list is tried automatically. -The default timeout is 10 seconds per gateway. - -```rust -use crypto_ctrng::{Ctrng, IpfsConfig, RandomBlockSource}; -use std::time::Duration; - -let beacon_key = "k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f"; - -// Custom gateways + default gateways appended automatically -let config = IpfsConfig { - gateways: vec!["https://my-gateway.example.com".into()], - ..Default::default() -}; -let mut ctrng = Ctrng::ipfs(beacon_key, Some(config)); -let block = ctrng.next_block().expect("at least one gateway should respond"); - -// Custom gateways only (no defaults), with a custom timeout -let config = IpfsConfig { - gateways: vec![ - "https://ipfs.filebase.io".into(), - "https://ipfs.io".into(), - ], - use_defaults: false, - timeout: Duration::from_secs(5), -}; -let mut ctrng = Ctrng::ipfs(beacon_key, Some(config)); -``` - -### DRBG with automatic reseeding (recommended) - -```rust -use crypto_ctrng::{Ctrng, MixedCtrng, ReseedingRng}; -use rand_core::RngCore; - -let beacon_key = "k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f"; - -let ipfs = Ctrng::ipfs(beacon_key, None); -let mixed = MixedCtrng::new(ipfs).unwrap(); -let mut rng = ReseedingRng::new(mixed).unwrap(); - -let mut key = [0u8; 32]; -rng.fill_bytes(&mut key); -``` - -### Custom reseed intervals - -```rust -use std::time::Duration; -use crypto_ctrng::{Ctrng, MixedCtrng, ReseedConfig, ReseedingRng}; - -let beacon_key = "k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f"; - -let ipfs = Ctrng::ipfs(beacon_key, None); -let mixed = MixedCtrng::new(ipfs).unwrap(); - -let config = ReseedConfig::new(1600, Duration::from_secs(3600)); // 50 blocks, 1 hour -let mut rng = ReseedingRng::with_config(mixed, config).unwrap(); -``` - -## Tests - -To run offline tests : - -```cargo test``` - -To run offline and online tests : - -```cargo test -- --include-ignored``` - -### Statistical verification - -Statistical testing is provided by the separate [`rng-statistical-tests`](https://github.com/spacecomputer-io/statistical-verification) library, which supports both **TestU01** and **PractRand**. - -TestU01 and PractRand are automatically downloaded and built during compilation - no manual setup required. - -To run statistical tests: - -```bash -cargo test --features testu01 # TestU01 SmallCrush -cargo test --features practrand # PractRand (1 MiB) -``` - - -## License - -This project is licensed under the terms of the MIT License. See the [LICENSE](LICENSE) file for details. - -## Contributing - -We welcome contributions to this project! If you have suggestions for improvements or new features, please open an issue or submit a pull request. From ce807049721a5ff909ff5d6b7366ad3486f41589 Mon Sep 17 00:00:00 2001 From: Toufic Date: Thu, 9 Apr 2026 18:17:04 +0200 Subject: [PATCH 2/2] update cargo.lock --- Cargo.lock | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 084249d..c282214 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -143,10 +143,10 @@ dependencies = [ "rand_chacha 0.3.1", "rand_core 0.6.4", "reqwest", - "statistical-verification", "serde", "serde_json", "sha2", + "statistical-verification", "thiserror 1.0.69", "zeroize", ] @@ -185,7 +185,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" dependencies = [ "libc", - "windows-sys 0.60.2", + "windows-sys 0.61.2", ] [[package]] @@ -909,16 +909,6 @@ dependencies = [ "windows-sys 0.52.0", ] -[[package]] -name = "statistical-verification" -version = "0.1.0" -source = "git+https://github.com/spacecomputer-io/statistical-verification.git#fd16ef0da4c74ed5e704e98a47d581e61a06ef71" -dependencies = [ - "bindgen", - "once_cell", - "rand_core 0.6.4", -] - [[package]] name = "rustc-hash" version = "1.1.0" @@ -1091,6 +1081,16 @@ version = "1.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" +[[package]] +name = "statistical-verification" +version = "0.1.0" +source = "git+https://github.com/spacecomputer-io/statistical-verification.git#202770127e65eec394b64666e0d4fd1e3cadea8f" +dependencies = [ + "bindgen", + "once_cell", + "rand_core 0.6.4", +] + [[package]] name = "subtle" version = "2.6.1"