NEXUS-Q is an open-source post-quantum cryptographic engine written in Rust

   

Protecting data, keys, and identities with standardized cryptography and an auditable security workflow.
A plain-language tour of the project lives on the website: nexus-q.link.

Current project status (checked 2026-10-23): GitHub release v4.1.1 is published and its Git tag points to the current main branch. Important: the existing nexusq-v4.1.1-provenance.json still records commit 5dd564d, and the previously published release binaries, checksums and SBOM were not regenerated when the tag moved. The tag therefore points to main, but the existing release assets do not yet have matching provenance for that commit. The release-tag manifest declares Rust 1.85, while current main declares Rust 1.88; the 1.88 requirement below applies to building current main, not automatically to every published package. Public endpoint checks confirm 4.1.1 availability for published crates.io packages, PyPI (nexusq, source distribution only), npm, RubyGems, Packagist, pub.dev, NuGet (Nexusq), and Maven Central Java (io.github.lecodev-26:nexusq) and Kotlin (io.github.lecodev-26:nexusq-kotlin) artifacts. These checks establish registry availability, not source-commit provenance for every registry package. nexusq-pki-cluster 4.1.1 was successfully published to crates.io on 2026-10-23 after updating the Cargo API token. The successful upload was confirmed by Cargo; public registry propagation may take a short time. nexusq-hsm is published. The NuGet 4.1.1 archive contains the .NET 9 assembly and native runtime assets for Linux x64/ARM64, macOS ARM64 and Windows x64; its publish workflow completed successfully for main commit 5b8a663 on 2026-10-23 (run details). Maven POM, JAR, sources JAR and Javadoc JAR endpoints returned HTTP 200 for both 4.1.1 artifacts. The Go module uses its own v0.1.0 version. SwiftPM's bare 4.1.1 tag still resolves to the original release commit 5dd564d; Git tag v4.1.1 points to current main. These tags are not equivalent. SwiftPM users must not assume these two tags identify the same source snapshot. The native ML-KEM/ML-DSA backend remains experimental and opt-in; RustCrypto remains the default production path. CI run 39820696137 for main commit 5b8a663 completed successfully: 62 jobs passed, two optional/manual jobs were skipped, and none failed. Its Cargo audit and Cargo deny jobs passed. The previously reported time advisory was addressed by updating the lockfile to time 0.3.47. On 2026-10-23, the newly published RUSTSEC-2026-0385 advisory for ctutils 0.4.2 was addressed by updating the workspace and native-backend lockfiles to ctutils 0.4.4 (the advisory fix requires Rust 1.87; current main requires Rust 1.88). Both lockfiles are covered by the native-backend security workflow. The Swift SDK workflow now retries its C runtime build up to three times to tolerate transient crates.io DNS/registry failures observed on hosted macOS runners; persistent failures still fail the job. RUSTSEC-2023-0071 for rsa remains an explicitly documented exception in .cargo/audit.toml and deny.toml; this is not a claim that every advisory is fixed. No independent external audit, FIPS 140-3 validation, certification, or production-readiness claim is made. See docs/V4_RELEASE.md and docs/NATIVE_RUNTIME_PACKAGING.md.

This is a quick orientation, not a substitute for the per-module documentation or release provenance. “Available” means the repository has an implemented path; it does not imply independent audit or certification.

The repository separates the cryptographic core from interfaces, optional services, and language bindings. These names describe repository components, not a claim that every package has identical maturity, platform support, or release provenance. Use the installation table and each binding's own documentation to confirm the package and target you need.

The repository already includes visual assets for the architecture flow, project overview and benchmark comparisons. Benchmark visuals are based on the documented measurements; consult the accompanying tables and run-specific notes rather than treating a graphic as a standalone performance guarantee.

NEXUS-Q is a post-quantum cryptographic security engine designed to protect:

It is intended as a cryptographic/security engine for applications and servers. The repository also defines hardware-provider abstraction points for future TPM, HSM, Secure Element, enclave and RISC-V integrations; the default software backend does not itself provide hardware isolation.

Every operation goes through the same building blocks: a password unlocks an encrypted vault (format F-01, atomic writes), keys are managed through their full lifecycle, data is protected with envelope encryption (format F-02), a deny-by-default policy engine gates actions, and security-relevant events go to an HMAC-authenticated audit log with rollback anchoring.

1. We do not invent cryptography. Only standardized algorithms and maintained cryptographic libraries; dependency audit status is documented explicitly.
2. Library-first. The core is a Rust library; the CLI, SDKs and server are layers on top.
3. Hardware-agnostic boundary. Hardware-provider interfaces are separated from the software backend; concrete hardware isolation is only claimed when a provider is implemented and tested.
4. Zeroization. Secrets are wiped from memory when no longer needed.
5. Auditability. Auditable security state changes and cryptographic actions are recorded in a tamper-evident, HMAC-authenticated log.
6. Security from the ground up. Threat model and cryptographic rules before code.

Current main build requirements: Rust 1.88 or newer (edition 2024, matching the current Cargo.toml MSRV) and Git. Published packages may have different source provenance and MSRV; check the specific package metadata when targeting an older toolchain. Additional SDK toolchains are only required when building a specific binding (C/C++, Python, Go, Ruby).

Target platforms: Linux (x86_64, aarch64); Android / Termux (aarch64); RISC-V (riscv64gc-unknown-linux-gnu), build verified; macOS and Windows release builds are validated by the V2 CI/release gate.

The reference document is docs/CRYPTOGRAPHY.md. Planned algorithms must not be described as available until they are implemented and tested.

Completed:

• Foundation documents, threat model, cryptographic rules.
• Crypto core: ML-KEM-768 hybrid with X25519, AES-256-GCM, ChaCha20-Poly1305, Ed25519, SHA-2, SHA-3, Argon2id, HKDF.
• Key management with full lifecycle.
• Encrypted vault (format F-01) with atomic writes.
• Envelope encryption (format F-02).
• Identities with signing, verification, rotation, revocation and signed credentials.
• Hardware abstraction traits for software, TPM, HSM, Secure Element and RISC-V.
• TRNG support with health checks and mixing.
• Cross-compilation to RISC-V verified.
• Storage: HMAC-authenticated audit log with rollback anchoring, backup bundle, storage DB.
• Policy engine with deny-by-default.
• CLI covering vault, key, data, sign, identity, credential and audit commands.

The benchmark tables below intentionally retain the recorded measurements, historical comparisons, and known caveats. They are real project benchmark results, not illustrative figures. Each dataset has its own context: local diagnostics, hosted-runner release gates, and historical Arena runs must not be compared as if they were one controlled experiment.

For reproducibility and fuller context, start with the PQC Benchmark Arena documentation, the benchmark index, the V4 release notes, and the linked per-run CI artifacts/reports. Hardware, CPU governor, runner environment, sample count, warmups, comparator versions, and aggregation method matter. Latency ratios are operation-specific; there is no composite score here. Lower latency is better, and a benchmark pass is not an end-to-end application performance or security certification claim.

NEXUS-Q is not presented as a universal performance leader. In the 2026-10-21 local x86-64 benchmark, the opt-in native backend was compared with the best eligible per-operation comparator using a matched AWS-LC RNG. Six of nine operations beat the comparator on both median and p95; the other three are close to parity: ML-DSA-65 signing (1.063× median / 1.115× p95), ML-KEM-1024 key generation (1.021× / 1.020×), and ML-KEM-768 key generation (1.015× / 1.013×). This is local diagnostic evidence from an Intel Core i3-N305 with the CPU governor set to powersave, not a hosted-runner release benchmark or a universal performance claim. The project owner accepted this result as sufficient to complete Issue #23, treating 1.00× as an ideal target rather than an absolute closure requirement; the remaining deltas are documented in docs/performance/ISSUE_23_FINAL_GATE_AUDIT_2026-10-21.md. The default nexusq-core build, CLI and SDKs still use RustCrypto for production call paths; the native path is opt-in and experimental. Lower latency is better.

_{v4.1.0 stable line, 2026-10-19: official 1.5× median-and-p95 production-path gate (opt-in native backend vs AWS-LC) from the green release CI on the merged v4.1.0 code — three alternating rounds per implementation, pooled medians and nearest-rank p95, 3,000 samples per operation per implementation on an AMD EPYC 7763 CI runner. The full PQC Benchmark Arena run of the same release (241 normalized measurements, eight comparators plus the V1/V1+zeroize/V3 controls) is retained as CI artifacts. Reported without a composite score.}

From the repository root, with Rust 1.88+ installed:

# build the workspace
cargo build --workspace --release

# create and inspect a vault
./target/release/nexusq vault create ./example.nqv
./target/release/nexusq vault status ./example.nqv
./target/release/nexusq health

# generate a signing key (prefer --password-file over typing a password)
./target/release/nexusq key generate ./example.nqv --algorithm ed25519 --purpose sign --password-file ./password.txt

# encrypt and decrypt data
./target/release/nexusq data encrypt ./example.nqv --key-id <key-id> ./secret.txt
./target/release/nexusq data decrypt ./example.nqv ./secret.txt.nqx ./secret.out

Treat password.txt as a secret: restrict its permissions and never commit it. For development, cargo build and cargo test work as usual, and the CLI binary is at target/debug/nexusq. To build for RISC-V see docs/CROSS_COMPILE.md. The signing-key example above explicitly uses Ed25519 (classical, not post-quantum); see docs/user/CLI.md for the CLI-supported algorithms and do not infer that every library-level ML-KEM/ML-DSA operation is exposed through the same CLI workflow. The commands are an orientation: create the password file and input file first, and substitute the actual key ID printed by key generation for <key-id>.

Release deployment:

cargo build --workspace --release
./deploy/package-release.sh

The generated archive contains the CLI, server, non-secret configuration example, deployment documentation, and SHA-256 manifests. It does not contain production tokens, vaults, private keys, or logs. For server installation and operations see docs/DEPLOYMENT.md and docs/SERVER.md.

The GitHub release v4.1.1 is available. The tag was retargeted to current main, but existing release assets and provenance were not rebuilt; see the status note above. The table below records public installation endpoints checked on 2026-10-23. Maven Central's Solr search index did not yet return the coordinates during this check, but the canonical repository served the 4.1.1 POMs, binaries, sources and Javadocs for both artifacts with HTTP 200; direct artifact URLs are the stronger availability check. Registry availability is not proof that every ecosystem package was built from the same Git commit. nexusq-pki-cluster 4.1.1 has now been uploaded successfully to crates.io; public registry propagation can take a short time.

The following coordinates are published and can be used directly:

<dependency>
  <groupId>io.github.lecodev-26</groupId>
  <artifactId>nexusq</artifactId>
  <version>4.1.1</version>
</dependency>

// Gradle Kotlin DSL
implementation("io.github.lecodev-26:nexusq:4.1.1")
implementation("io.github.lecodev-26:nexusq-kotlin:4.1.1")

• The Go, PHP, Ruby, TypeScript, Java (JNA), Kotlin (JNA) and Dart bindings are thin FFI wrappers over the C SDK (libnexusq). Follow the language-specific setup instructions in bindings/ and docs/NATIVE_RUNTIME_PACKAGING.md; platform support and automatic runtime download behavior differ by SDK.
• The Python package is a native extension module built from crates/nexusq-py (PyO3). The PyPI 4.1.1 upload currently contains an sdist, not a platform wheel.
• The C#/.NET binding uses P/Invoke and the Swift binding links the C SDK through a Swift Package Manager system-library target. Ensure the native library is available as described in the relevant binding docs.
• The C SDK is consumable directly from C and C++; build it from source with cargo build -p nexusq-c --release or use the C SDK package.
• The GitHub release archive ships the CLI/server and native runtime assets; it is not a replacement for installing the C SDK development headers.
• Registry availability is a distribution channel, not a security validation claim. See the security and assurance section below.

User-facing documentation starts at docs/user/README.md, with a task-oriented getting started guide, installation instructions, CLI guide, SDK guide, and troubleshooting guide. Technical and reference documentation lives in docs/:

V1–V4 are engineering version lines/snapshots, not proof of production readiness. A GitHub release does not imply an independent security audit, certification, FIPS validation, or production readiness; the same applies to registry publication, which is a distribution channel and not a validation claim. The V4 native backend remains experimental and opt-in; it is wired into nexusq-core behind the native-backend feature but is not enabled by default in the core, CLI, server, or SDKs. The performance gate result applies to the benchmarked backend and must not be read as an end-to-end application performance claim. Check current main CI before relying on any validation statement.

Report suspected vulnerabilities privately through GitHub Security Advisories. See SECURITY.md.

Issues, reproducible bug reports, documentation improvements, and focused pull requests are welcome. Before opening a change:

1. Read the architecture, threat model, cryptographic rules, and security policy relevant to the change.

2. Keep cryptographic primitives delegated to established libraries; do not introduce home-grown cryptography or silently change serialized formats.

3. Add or update tests and documentation alongside behavior changes. For performance work, include reproducible measurements and preserve the benchmark conditions and raw evidence.

4. Run the relevant local checks before submitting. A useful baseline for Rust changes is:

   cargo fmt --all -- --check
   cargo test --workspace
   cargo build --workspace --release

   Run the checks applicable to the crates and SDKs you changed; CI remains the authoritative check for the full supported matrix.

5. Describe security-impacting changes and compatibility implications clearly in the pull request. Never include secrets, private keys, vault contents, production credentials, or sensitive logs.

Please report suspected vulnerabilities privately using the process in SECURITY.md, rather than publishing exploitable details in a public issue.

Dual-licensed under your choice of the MIT License or the Apache License 2.0. This follows the Rust ecosystem convention (the same choice as Rust, Tokio and Serde).