NEXUS-Q is a Rust engine for protecting data, keys and identities with ML-KEM, ML-DSA and a tamper-evident audit log, plus an honest account of what it does and does not prove. This page explains the whole project, so you do not have to audit the repository to understand it.
A post-quantum cryptographic security engine. It is a library first: a Rust core that does all the cryptography, with a command line, an HTTP server and language SDKs layered on top. It is meant to be embedded in applications and servers that need to protect secrets for the long term.
Authenticated encryption of files and streams, with envelope encryption (format F-02) so payloads are protected under a key that is itself protected.
The full key lifecycle: generation, rotation, revocation and destruction, stored in an encrypted vault (format F-01) with atomic writes.
Digital signatures, signature verification, identity rotation and revocation, and signed verifiable credentials.
Large quantum computers would break the public-key schemes in wide use today (RSA, elliptic curves), and data recorded now could be decrypted later. NEXUS-Q uses the NIST-standardized lattice algorithms ML-KEM and ML-DSA, and pairs the key exchange with classical X25519 as a hybrid.
We do not invent cryptography. Every primitive is a standardized algorithm implemented by a maintained library. Deviations need a written architecture decision record. The project also states plainly that it does not claim every dependency has been independently audited.
Every operation goes through the same building blocks. Policy decides who may act, the vault guards the keys, and security-relevant events are written to an audit log that detects tampering.
A password goes through Argon2id to unlock the encrypted vault. The vault holds keys at rest and is written atomically.
Generate, rotate, revoke and destroy keys. Secrets are zeroized in memory when they are no longer needed.
Hybrid ML-KEM + X25519 for key exchange, AES-256-GCM or ChaCha20-Poly1305 for data, Ed25519, ML-DSA-65 or SLH-DSA for signatures.
A deny-by-default policy engine decides which actions are allowed before they happen.
An HMAC-authenticated audit log with rollback anchoring makes tampering and truncation detectable.
The core is a Rust library. The CLI, the server and the SDKs are thin layers on top and contain no cryptography of their own.
Provider traits exist for software, TPM, HSM, Secure Element and RISC-V. Hardware isolation is only claimed when a provider is implemented and tested. The default software backend does not provide it.
The threat model and the cryptographic rules were written before the code, and they are part of the repository.
A Cargo workspace of five Rust crates, plus bindings for other languages and a reproducible benchmark arena.
| Component | What it is |
|---|---|
| nexusq-core | The library. All cryptography, vault, key management, identity, policy, storage and hardware abstraction live here. |
| nexusq-cli | The nexusq binary: vault, key, data, sign, identity, credential and audit commands. A thin wrapper over the library. |
| nexusq-server | The nexusq-server binary and authenticated HTTP service, with health, readiness and Prometheus-style metrics endpoints. |
| nexusq-c · nexusq-py | The C SDK and the Python binding, built on the core library. |
| bindings/go · php · ruby | Language bindings covered by a dedicated SDK CI workflow. |
| arena/ | The PQC Benchmark Arena: pinned external implementations, a normalized JSONL protocol and retained CI artifacts. |
| fuzz/ · artifact-archive/ | Fuzz targets, and the archived V1/V2/V3 evidence with SHA-256 manifests. |
Linux x86_64 and aarch64, Android/Termux aarch64, and RISC-V (riscv64gc) with a verified build.
Rust 1.85 or newer (edition 2024) and Git. SDK toolchains are only needed for the binding you build.
Encrypted vault, envelope format, backup bundles and a storage database, all with documented formats.
Request IDs, aggregate metrics, health and readiness probes. Secrets are kept out of logs.
The core is only allowed to use six families of primitives. Anything outside them, such as raw RSA or custom MACs, is forbidden by the project's own rules.
| Family | Purpose | Implemented |
|---|---|---|
| Randomness | Entropy for keys, nonces and salts | OS CSPRNG, plus TRNG support with health checks and mixing |
| Hashing | Digests and commitments | SHA-2, SHA-3 |
| KDF | Passwords and key material to keys | Argon2id, HKDF |
| AEAD | Symmetric authenticated encryption | AES-256-GCM, ChaCha20-Poly1305 |
| KEM | Post-quantum key encapsulation | ML-KEM-768 and ML-KEM-1024, hybrid with X25519 |
| Signatures | Authenticity and non-repudiation | Ed25519, ML-DSA-65, SLH-DSA-SHAKE-128f |
Planned algorithms are never described as available until they are implemented and tested. The reference document is docs/CRYPTOGRAPHY.md.
NEXUS-Q is not a performance leader, and the project says so. The numbers below come from the repository's own benchmark records. They are the baseline the next versions are measured against.
V1, V2 and V3 are engineering version lines, not certifications. A GitHub release here does not mean an audit, a certification, production readiness or publication to a package registry.
The frozen engineering baseline: crypto core, vault, keys, identities, policy, audit log, CLI, server and SDKs. Its Arena result showed NEXUS-Q slower than the fastest implementations, which became the main target.
FrozenCorrectness, interoperability, security fuzzing, backend strategy and release gates. The final record claims no performance improvement over V1, and the performance question stayed open.
Frozen on nexusqv2Hardened implementation, the reproducible Arena, corrected benchmark sampling and a downloadable evidence archive with a SHA-256 manifest. Integrated into main.
Current releasePlanned architecture-specific kernels: AVX2 and NEON prototypes behind explicit feature dispatch, with a portable fallback. Optimized paths become the default only after differential tests, test vectors, fuzzing, constant-time review and repeatable same-hardware benchmarks.
Planned, not a releaseCryptographic software earns trust slowly. This is the project's own statement of its current assurance level.
Found a vulnerability? Report it privately through GitHub Security Advisories, not a public issue. See SECURITY.md.
You need Rust 1.85 or newer. Linux and Android/Termux are the environments exercised most.
# clone and build the workspace
git clone https://github.com/lecodev-26/nexus-q
cd nexus-q
cargo build --workspace --release./target/release/nexusq vault create ./example.nqv ./target/release/nexusq vault status ./example.nqv ./target/release/nexusq health
./target/release/nexusq key generate ./example.nqv \ --algorithm ed25519 --purpose sign \ --password-file ./password.txt ./target/release/nexusq key list ./example.nqv
./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
Prefer --password-file over typing a password on the command line, and never commit that file. The full command list is in the CLI guide. Server setup is in docs/SERVER.md.
Everything below lives in the repository. Start with the user guide, then go as deep as you need.
The project does not claim production readiness. It is an engineering project with strong CI gates, but there has been no independent audit or certification. Evaluate it, review it, and treat it accordingly.
No independent external audit has been completed, and none is implied by a GitHub release. The project states it will link a public evidence package from the repository if one exists.
V1 was built to be correct and secure first. Its Arena run measured it roughly 2 to 4.5 times slower than the fastest implementations. V3 keeps zeroization and hardening and accepts the cost. V4 plans optimized AVX2 and NEON kernels, enabled by default only after a strict validation checklist.
A hybrid keeps the key exchange protected as long as at least one of the two schemes holds up. That is the usual reasoning for hybrids while post-quantum algorithms are still young in deployment.
The repository includes a C SDK, a Python binding and Go, PHP and Ruby bindings, covered by a dedicated SDK CI. They are not published to package registries, so you build them from source. See the SDK guide.
You can choose either the MIT license or the Apache License 2.0, the same dual license used by much of the Rust ecosystem.
Read the threat model, run the Arena yourself, review the code, and open an issue or a pull request. Performance work for V4 is tracked in Issue #23. Security reports go through GitHub Security Advisories.