cahlen/keeloq-python

# keeloq-python 对 [KeeLoq](https://en.wikipedia.org/wiki/KeeLoq) 分组密码的代数 + 神经密码分析——这是对 2015 年最初存在于本仓库中基于 SAT 的攻击的 2026 年现代化升级。 ## 目录结构 针对减轮 KeeLoq 的两个独立密码分析流水线，均可通过单个 `keeloq` CLI 驱动： 1. **代数 / SAT** — Python 3，结合具有原生 XOR 子句的 CryptoMiniSat，以及纯 CNF 和 XOR 感知的 ANF 编码器。在 RTX 5090 上，能够以 **64 轮 / 0 提示 / 4 个明文-密文对在 0.247 秒内** 恢复 64 位密钥。而最初的 2015 年流水线处理更难的变体（160 轮，25 个密钥位提示，2 个明文-密文对）需要 14 个小时。 2. **神经差分 (Gohr 2019 风格)** — 在 GPU 位切片 KeeLoq 实现上训练的 PyTorch ResNet-1D-CNN 区分器（在 5090 上约 10⁶ 对/秒），结合贝叶斯束搜索密钥恢复，并将区分器无法解析的剩余位交接给 SAT 后缀处理。独特之处在于：KeeLoq 每轮 1 位的密钥调度允许贝叶斯搜索一次猜测一位，而不是像 Gohr 最初的 SPECK 攻击那样猜测 16 位的子密钥块。 2015 年的流水线（SageMath + miniSAT + 手工编辑的多项式系统）已冻结在 `legacy/` 中，并通过 Docker 托管的 `python:2.7` 一致性测试针对现代流水线进行了验证。 ## 系统要求 - Linux x86_64, Python 3.12 - [`uv`](https://docs.astral.sh/uv/) 用于依赖管理 - **可选**：CUDA 12.8+ GPU（RTX 5090 或类似设备）——神经流水线以及针对 GPU 位切片密码的属性测试需要此项；代数攻击在 CPU 上运行良好。 - **可选**：Docker——在一个临时的 `python:2.7` 容器内运行传统的 2015 Python 2 脚本以进行一致性测试。 ## 安装 ``` uv sync --all-extras ``` ## 快速入门 — 代数攻击 在 64 轮、4 个明文-密文对、零提示的条件下恢复 64 位密钥： ``` KEY=0011010011011111100101100001110000011101100111001000001101110100 PT1=01100010100101110000101011100011 PT2=11010011100101010000111100001010 CT1=$(uv run keeloq encrypt --rounds 64 --plaintext $PT1 --key $KEY) CT2=$(uv run keeloq encrypt --rounds 64 --plaintext $PT2 --key $KEY) uv run keeloq attack --rounds 64 \ --pair "$PT1:$CT1" --pair "$PT2:$CT2" \ --encoder xor --solver cryptominisat --timeout 120 ``` 典型实际耗时：**< 1 秒**。 复现 2015 README 基线（160 轮，25 个提示，2 个明文-密文对，传统代码对比）： ``` uv run keeloq benchmark ``` ## 快速入门 — 神经密码分析 端到端，单条命令（Δ 搜索 + 训练 + 攻击合成目标）： ``` uv run keeloq neural auto --rounds 64 --trained-depth 56 \ --samples 10000000 --pairs 512 \ --checkpoint-out checkpoints/d64.pt ``` 在 RTX 5090 上的训练时间约 60 分钟。或者跳过训练，直接从 Hugging Face 拉取已发布的检查点： ``` mkdir -p checkpoints hf download cahlen/keeloq-neural-distinguishers d64.pt --local-dir checkpoints/ ``` 然后攻击同一密钥下的任何新密文： ``` uv run keeloq neural recover-key --checkpoint checkpoints/d64.pt \ --rounds 64 --diff-pair ":" --sat-pair ":" \ --beam-width 16 --sat-timeout 120 ``` ### 工作原理 — KeeLoq 上的 Gohr 模式 在固定深度 **D**（例如 56）下训练 ResNet-1D-CNN 区分器，以将选择输入差分的密文对与随机对区分开来。**M = D + K** 轮的攻击通过贝叶斯束搜索（`recover_prefix`）剥离 `K` 轮，从而恢复外部的 `K` 个密钥位。剩余的后缀位被交接给代数流水线的 XOR 感知编码器 + CryptoMiniSat。每一个恢复的密钥在报告 `SUCCESS` 之前都会经过密码验证（`cipher.encrypt(pt, k, rounds) == ct`）。 **双数据对流。** `--diff-pair` 承载差分密文对 `(c₀, c₁)`——包含两个密文，供神经区分器使用。`--sat-pair` 承载已知的 `plaintext:ciphertext`（明文:密文）对——供 SAT 求解器使用。这两者是不同的，因为差分攻击不需要已知明文；只有 SAT 阶段需要。 **密钥调度约束。** KeeLoq 的密钥每 64 轮循环一次；在少于 64 轮的情况下，位 `K_rounds..K_63` 永远不会被引用，如果不提供提示就无法恢复。因此，低于 64 轮的攻击会自动为不受约束的范围填充 `extra_key_hints`——这由 `keeloq neural auto` 自动处理。 ### Hugging Face 上的预训练区分器 检查点发布在 [**cahlen/keeloq-neural-distinguishers**](https://huggingface.co/cahlen/keeloq-neural-distinguishers)，附有完整的模型卡片，涵盖训练配置、评估指标、架构和攻击过程。当前可用性： | 文件 | 训练深度 | 攻击目标 | 验证集准确率 | ROC-AUC | |---|---:|---:|---:|---:| | `d64.pt` | 56 | 64 轮 | 0.752 | 0.828 | | `d96.pt` | 88 | 96 轮 | (即将推出) | (即将推出) | | `d128.pt` | 120 | 128 轮 | (即将推出) | (即将推出) | 每个 `.pt` 文件都嵌入了其完整的 `TrainingConfig`，因此只需使用随机种子即可复现结果。 ## 通过 Unix 管道组合流水线 代数流水线也作为独立的阶段公开，在 stdin/stdout 上使用 JSON： ``` keeloq generate-anf ... | keeloq encode ... | keeloq solve ... | keeloq verify ... ``` 这对于检查中间产物（ANF 多项式系统、DIMACS CNF、SAT 结果 JSON）或替换为备选编码器/求解器非常有用。 ## 运行测试 ``` uv run pytest -n auto -m "not slow" # fast suite — ~30 s on the 5090 box uv run pytest -n auto # full suite, including GPU and slow ``` 测试标记： - `@pytest.mark.gpu` — 需要 CUDA GPU；在仅限 CPU 的机器上自动跳过。 - `@pytest.mark.slow` — 耗时数秒的测试；从默认的快速测试套件中排除，但会运行端到端的攻击和基准冒烟测试。 - `@pytest.mark.legacy` — 需要 Docker + `python:2.7` 镜像；运行 2015 年的脚本并验证一致性。 ## 项目布局 ``` src/keeloq/ # modern Python 3 pipeline cipher.py # readable reference cipher (rounds-parameterized) gpu_cipher.py # bit-sliced CUDA cipher (property-test oracle + training-data generator) anf.py # ANF polynomial system generator encoders/ # pure-CNF + XOR-aware encoders solvers/ # CryptoMiniSat wrapper + DIMACS subprocess wrapper attack.py # SAT-only attack pipeline with mandatory cipher-verify neural/ # Phase 3b neural cryptanalysis data.py # training pair generator (differential + random) differences.py # Δ candidate search distinguisher.py # ResNet-1D-CNN + training loop + checkpoint I/O evaluation.py # accuracy / ROC-AUC / TPR@FPR metrics key_recovery.py # partial_decrypt_round + recover_prefix beam search hybrid.py # neural-prefix + SAT-suffix orchestration cli_neural.py # `keeloq neural {train, evaluate, recover-key, auto}` cli.py # main Typer entry point legacy/ # frozen 2015 Python 2 scripts (run via Docker) benchmarks/ matrix.toml # algebraic benchmark matrix (Phase 1) bench_attack.py # runner neural_matrix.toml # neural-hybrid vs pure-SAT matrix (Phase 3b) bench_neural.py # runner tests/ # pytest suite (unit + property + integration + compat) checkpoints/ # trained distinguisher checkpoints (not committed; reproducible) docs/ superpowers/specs/ # design docs per modernization phase superpowers/plans/ # task-by-task implementation plans phase3b-results/ # Δ search tables, eval reports, benchmark results ``` ## 历史背景（2015 年起源） 最初的 2015 年流水线是这次现代化的目标。已原封不动地冻结在 `legacy/` 中： - `keeloq-python.py` / `keeloq160-python.py` — Python 2 编写的 KeeLoq 参考实现（528 轮和 160 轮）。 - `sage-equations.py` / `polynomial-vars.py` — 为 SageMath 输出 ANF 多项式系统和变量列表。 - `sage-CNF-convert.txt` — SageMath 驱动程序，通过 PolyBoRi 的 `CNFEncoder` 将 ANF 转换为 DIMACS CNF。 - `parse-miniSAT.py` — 从 miniSAT 输出中恢复 64 位密钥。 原 2015 年 README 文本（为提供历史参考保留如下）： 有关追踪从 2015 年状态到当前代码的路径的设计文档，请参见 [`docs/superpowers/specs/`](docs/superpowers/specs/)。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：CNN, CryptoMiniSat, CUDA, IaC 扫描, KeeLoq, Python, PyTorch, SAT求解器, Vectored Exception Handling, 云资产清单, 代数分析, 凭据扫描, 分组密码, 密码学, 密钥恢复, 差分分析, 手动系统调用, 无后门, 比特切片, 深度学习, 神经密码学, 请求拦截, 贝叶斯搜索, 逆向工程