isazajuancarlos/quipu
GitHub: isazajuancarlos/quipu
Quipu 是一个后量子混合密码学编码库，为静态数据提供对称加密、公钥加密、流式加密、混合签名与符号化表示，支持多语言绑定。
Stars: 0 | Forks: 0
# Quipu
[](LICENSE)
[](https://crates.io/crates/quipu)
[](https://docs.rs/quipu)
[](https://github.com/isazajuancarlos/quipu/actions/workflows/ci.yml)
[](#modos)
带有**加密保护**和**专属符号体系**的编码库。
## 功能
保护数据并将其表示为**符号**（紧凑文本、字形或图像），
过程可逆且经过身份验证。
```
datos → KDF(passphrase+pepper) → AEAD → contenedor → codec base-N → diccionario → símbolos
```
## 模式
| 模式 | API (Rust) | 描述 |
|---|---|---|
| 对称（passphrase） | `api::encode` / `api::decode` | Argon2id + XChaCha20-Poly1305 |
| 后量子（公钥） | `api::encode_to_recipient` / `decode_as_recipient` | 混合 **X25519 + ML-KEM-1024**（X-Wing 风格的绑定记录） |
| 视觉通道 | `api::encode_to_image` / `decode_from_image` | **PNG** 无损输出 |
| 稳健通道（打印） | `api::encode_to_robust_image` / `decode_from_robust_image` | + **Reed-Solomon**（纠正通道错误） |
| 原生字形 | `api::encode_to_glyph_image` / `decode_from_glyph_image` | 专属字形表，易于识别 |
| 在线（强化） | `api::encode_online` / `decode_online` | **可验证 VOPRF**（DLEQ 证明）：客户端可检测恶意服务器 |
| 签名（真实性） | `api::encode_signed` / `decode_verified` | 混合签名 **Ed25519 + ML-DSA-87**（AND 组合器）。可验证真实性与不可否认性；**无**机密性 |
| 三重签名（高保障，功能 `slh`） | `api::encode_signed_triple` / `decode_verified_triple` | 三重混合签名 **Ed25519 + ML-DSA-87 + SLH-DSA-256s**（3选3 AND）：只要 {曲线, 格, hash} 中有 ≥1 个存活，即不可伪造。Opt-in；签名大小约 34 KB |
| 流式（大文件） | `api::encrypt_stream` / `decrypt_stream` | 分块加密（内存有限）适用于大型静态数据；抗截断/重排/拼接。容器 `QST1` |
| 蜜罐 / Honey（功能 `honey`） | `honey::encrypt_pin` / `decrypt_pin`（及通用 `encrypt`/`decrypt`） | 针对低熵 secret（PIN、助记词）的 **Honey Encryption**：任何错误的 passphrase 都会解密为**另一个看似合理的 secret**，而不是报错 → 无暴力破解预言机。Opt-in。**设计上无身份验证**（tag 将成为预言机）；不能替代核心 AEAD，仅适用于均匀序列 |
## 字典（可插拔符号体系）
- `dictionaries::ascii94()` — 94 个 ASCII 符号（通用复制粘贴）。
- `dictionaries::flagship()` — 4096 个字形（12 比特/符号，密度约 2 倍）。
- `dictionaries::from_range(start, count)` — 自定义符号表。
- `glyphopt` — 通过最大可分性进行字形选择（AI 字形的基础）。
## 字形库
相同的加密 payload 可以表示为紧凑文本、PNG 图像，
或使用**专属字形表**（几何形状或有机生成）。
符号体系是**公开的**（Kerckhoffs 原则）：不增减安全性，仅作表示。
| 字形表 | 符号中的 secret | 原生字形 | 生成字形 |
|---|---|---|---|
|  |  |  |  |
## 安全与强化
- **预处理层**：NFKC 标准化、pepper、Padmé 填充（隐藏长度）、上下文绑定 (AAD)、HKDF（子密钥分离）。
- **反黑客**：内存中的密钥清除（`zeroize`）、常数时间比较、验证 KDF 参数、统一错误处理。
- **黑客机器人**：内部红队（篡改/截断/唯一性）。发现并修复了由恶意 Argon2 参数引发的 DoS 漏洞。
- **Security Lab**（功能 `lab` / `lab-offline`，不包含在已发布的构建中）：**自适应**红队，会自我攻击。在 CI 中的核心（格式泄漏 + 伪造签名）包含链式语料库和元测试，如果反黑客防御减弱则会失败；以及一个**隔离的离线沙箱**（无网容器）用于 AI 加速的时间和猜测成本测试。
`cargo run --example securitylab --features lab` · `bash lab/run.sh`。参见
[`lab/README.md`](lab/README.md) 和 `THREAT_MODEL.md` §9。
## 使用 (Rust)
```
use quipu::api::{encode, decode, Options};
use quipu::dictionaries;
let dict = dictionaries::ascii94();
let sym = encode(b"secreto", "passphrase", &dict, &Options::default());
let data = decode(&sym, "passphrase", &dict, b"").unwrap();
```
混合签名（可由第三方验证真实性，后量子）：
```
use quipu::api::{encode_signed, decode_verified};
use quipu::{dictionaries, pqsign};
let dict = dictionaries::ascii94();
let (vk, sk) = pqsign::generate_keypair();
let signed = encode_signed(b"acta oficial", &sk, &dict);
let msg = decode_verified(&signed, &vk, &dict).unwrap(); // falla si se altera
```
## 使用 (Python)
```
pip install quipu-crypto # se instala como "quipu-crypto", se importa como "quipu"
```
```
import quipu
s = quipu.encode(b"secreto", "passphrase")
assert quipu.decode(s, "passphrase") == b"secreto"
# 后量子
pub, sec = quipu.generate_keypair()
s = quipu.encode_to_recipient(b"secreto", pub)
assert quipu.decode_as_recipient(s, sec) == b"secreto"
# 混合签名（真实性，后量子）
vk, sk = quipu.generate_signing_keypair()
signed = quipu.encode_signed(b"acta oficial", sk)
assert quipu.decode_verified(signed, vk) == b"acta oficial" # falla si se altera
# 大数据 Streaming AEAD（二进制输出，非符号）
blob = quipu.encrypt_stream(b"...datos grandes...", "passphrase")
assert quipu.decrypt_stream(blob, "passphrase") == b"...datos grandes..."
```
## 使用 (Node.js)
```
npm install quipu-crypto # binarios precompilados: linux-x64, darwin-x64, darwin-arm64, win32-x64 (sin toolchain de Rust)
```
```
import * as quipu from 'quipu-crypto';
const blob = quipu.encryptStream(Buffer.from('...datos grandes...'), 'passphrase');
quipu.decryptStream(blob, 'passphrase'); // -> Buffer
const { publicKey, secretKey } = quipu.generateKeypair(); // post-cuántico
const c = quipu.encryptToRecipient(Buffer.from('secreto'), publicKey);
quipu.decryptAsRecipient(c, secretKey);
```
API 是**同步的**（运行 Argon2id；对于服务器，请从
`worker_thread` 调用）。参见 [`bindings/node/README.md`](bindings/node/README.md)。
## 使用 (Go)
```
go get github.com/isazajuancarlos/quipu/bindings/go@v0.7.0 # cgo: requiere CGO_ENABLED=1 y un compilador de C
```
```
import quipu "github.com/isazajuancarlos/quipu/bindings/go"
blob, err := quipu.EncryptStream([]byte("...datos grandes..."), "passphrase", quipu.StreamOptions{})
plain, err := quipu.DecryptStream(blob, "passphrase", nil)
```
符合语言习惯的 `(result, error)` API；使用 `errors.Is` 处理哨兵错误。注意：目前
链接需要检出代码库（cgo 链接 `target/release/libquipu_capi.a`）；
首先使用 `cargo build -p quipu-capi --release` 编译 staticlib。参见
[`bindings/go/README.md`](bindings/go/README.md)。
## 使用 (C / 其他语言)
稳定的 C ABI 位于 [`bindings/c`](bindings/c)（crate `quipu-capi`）。
编译动态/静态库和通过
cbindgen 生成的 `quipu.h` 头文件，使得任何具有 C FFI 的语言（Node.js, Go, Ruby, ...）
都能使用 Quipu。其接口与 Python 绑定保持对等。
参见 [`bindings/c/README.md`](bindings/c/README.md)。
```
#include "quipu.h"
uint8_t *blob = NULL; size_t n = 0;
if (quipu_encrypt_stream(data, len, "passphrase", NULL, 0, 0, &blob, &n) == QUIPU_OK) {
/* ... usar blob ... */
quipu_bytes_free(blob, n); /* se limpia al liberar: sin residuo de secretos */
}
```
## 功能示例
所有模式的往返测试，可直接运行：
```
cargo run --example quickstart # Rust (examples/quickstart.rs)
python examples/quickstart.py # Python (examples/quickstart.py)
```
## 构建与测试
```
cargo test # tests unit + property
cargo clippy --all-targets # lint
cargo run --example demo # demo simétrico + glifos
cargo run --example v2demo # post-cuántico + OPRF + imagen
cargo run --example hackerbot # red-team
cargo run --example testplatform --release # batería completa
cargo run --example securitylab --features lab # laboratorio de seguridad (red-team adaptativo)
cargo run --example redteam --features "lab slh honey" --release # red-team consolidado (todas las superficies)
bash lab/run.sh # banco offline aislado (timing + guessing) — Etapa B
# Coverage-guided Fuzzing（libFuzzer, nightly）。Targets: parse_container,
# honey_decrypt, unpad, codec_roundtrip.
cargo +nightly fuzz run honey_decrypt
# Python Bindings
source venv/bin/activate
maturin develop --features python
python tests/python/test_quipu.py
```
## 状态
v1 + v1.1 + v2 + AEAD 流式传输 (`QST1`) + honey (`QHNY`) + 签名（混合
Ed25519+ML-DSA-87 和带 SLH-DSA 的三重签名）已通过严格的 TDD 实现。
**207 个 Rust 测试 + Wycheproof + 15 个 Python 测试** 通过，clippy 无警告，模糊测试无
崩溃，Miri 无 UB。基于 C ABI 的多语言绑定，每个都有
跨语言互操作：**10 个 ABI + C 集成测试，12 个 Node，12 个 Go**。
后量子参数处于 **NIST 安全类别 5 (CNSA 2.0)**：
**ML-KEM-1024** 和 **ML-DSA-87**。带有**可验证 VOPRF**（DLEQ 证明）的在线模式，X-Wing 风格绑定记录的混合 KEM，**混合签名 Ed25519 +
ML-DSA-87**（AND 组合器），以及
自有的**预审计**（参见 `INFORME_PREAUDITORIA.txt` 和 `MODELO_DE_AMENAZA.txt`）。
**Security Lab**（自托管的自适应红队）：CI 中的 14 项攻击
（`--features lab`） + 离线时间/猜测沙箱（`--features lab-offline`）。
## 文档
- [`docs/SPEC.md`](docs/SPEC.md) — **技术规范**（容器格式、
KDF、混合模式、VOPRF/DLEQ、域分离）。
- [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) — 威胁模型 (EN)
· 原始版 [`MODELO_DE_AMENAZA.txt`](MODELO_DE_AMENAZA.txt) (ES)。
- [`docs/PRE_AUDIT.md`](docs/PRE_AUDIT.md) — 内部预审计 (EN)
· 原始版 [`INFORME_PREAUDITORIA.txt`](INFORME_PREAUDITORIA.txt) (ES)。
- [`SECURITY.md`](SECURITY.md) — 安全策略与漏洞报告。
- [`docs/RELEASES.md`](docs/RELEASES.md) — 如何验证 release 的真实性
(PEP 740 证明 + sigstore/cosign 签名)。
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — 如何贡献 · [`CHANGELOG.md`](CHANGELOG.md)。
- [`LICENSING.md`](LICENSING.md) — 双重许可模式。
- [`docs/announcement.md`](docs/announcement.md) — 设计文章 (EN/ES)。
- [`docs/superpowers/specs/2026-07-01-quipu-security-lab-design.md`](docs/superpowers/specs/2026-07-01-quipu-security-lab-design.md)
— **Security Lab**（自适应红队，功能 `lab`）设计。
## 许可证
**双重许可**模式（open-core）：
- **AGPL-3.0-or-later** 用于开源用途（参见 `LICENSE`）。
- **商业许可证** 用于闭源专有产品或不公开源码的 SaaS。
- **OPRF 服务器**还作为付费的**托管服务**提供。
详情参见 [`LICENSING.md`](LICENSING.md)。联系方式：isazajuancarlos@gmail.com
标签：MITM代理, Rust, 可视化界面, 后量子密码学, 多语言绑定, 密码学, 手动系统调用, 数据加密, 日志审计, 编码与解码, 网络流量审计, 逆向工具, 通知系统