How agohr/deep_speck works
1. What this repo is
This is a research codebase for Speck32/64 cryptanalysis using deep learning. The repository is organized around three concerns: training neural distinguishers, using them in key-recovery / key-rank attacks, and generating analytical evidence with C++ search tools.
2. Core cipher layer
The Python speck.py module, plus simple_net/speck.py, provide the Speck32/64 primitive and the data-generation helpers used by the experiments. This is the shared foundation for training, evaluation, and attacks: all higher-level scripts consume ciphertext pairs or differences produced through this layer.
3. Neural distinguisher assets
The .h5 files (net5_small.h5, net6_small.h5, net7_small.h5, net8_small.h5, plus the files in simple_net/) are pre-trained Keras models. The architecture definitions live alongside them, such as single_block_resnet.json and simple_net/simple_7r_model_preproc.json, so model loading is split between weights and network topology.
4. Training pipeline
train_5_rounds.py is the main “from scratch” training entrypoint for the 5-round distinguisher described in the paper. train_nets.py appears to be a broader training driver for other round counts or variants. These scripts produce model artifacts that are then reused by evaluation and attack code rather than retraining inside the attack path.
5. Evaluation and benchmarking
eval.py evaluates the supplied pre-trained distinguishers in two regimes: real-vs-random and real-difference settings. This is the main script for measuring classifier behavior independently of a full key-recovery attack, and it consumes the stored Keras models plus the associated data files.
6. Key-recovery attack path
test_key_recovery.py is the end-to-end attack demonstrator. It runs the 11-round attack repeatedly and, at the end of the script, includes a 12-round variant using the same pipeline. The attack code depends on the trained distinguishers and writes summary outputs (run_sols1.npy, run_sols2.npy, run_good.npy) that capture recovered subkey error and solvability indicators.
7. Key-rank experiments
key_rank.py computes rank statistics for the 9-round neural-distinguisher attack under varying ciphertext-pair budgets. key_rank_ddt.py performs the same experiment but swaps the learned distinguisher for a difference-distribution-table-based distinguisher. The DDT path depends on large precomputed transition tables rather than neural model inference.
8. Difference-distribution / Markov-model analysis
The cpp/ subtree contains the heavy offline analysis tools. speck.cpp builds speck_analysis, which validates claims about differential behavior, key-search distinguishers, and transition probabilities. speck_ddt.cpp builds speck_ddt, which computes large round-by-round difference distributions for the specific input difference used in the paper and writes them to disk for later Python loading.
9. Large precomputed analysis data
The supplementary_data/ tree stores the outputs of expensive experiments: 9-round attack rank traces, key-dependence measurements for the 7-round distinguisher, and the learning history of the 5-round network. These artifacts are not core logic, but they are important inputs for reproducing the paper’s figures and for validating claims without rerunning the full experiments.
10. Wrong-key and nonuniformity analysis
key_nonuniformity.py analyzes whether the 7-round distinguisher’s quality depends on the key. It consumes the supplied wrong-key response profiles and related .npy statistics. The data_wrong_key_*.npy files are the supporting measurement data for that analysis.
11. Key averaging and data generation
key_averaging.py implements the KeyAveraging method from the paper and also generates higher-quality training data from its output. This sits between data synthesis and training: it is not an attack itself, but a preprocessing/label-improvement step for building better distinguishers.
12. Neural input-difference search
neural_difference_search.py is a separate experimental pipeline that trains a small distinguisher, then uses few-shot learning plus an optimization search to find more favorable input differences. This is an exploratory tool that probes the relationship between the learned model and differential structure, rather than a direct attack script.
13. Data and file-flow boundaries
The repository’s data flow is mostly offline and file-based: training scripts write model weights, attack scripts read models and ciphertext pairs, C++ tools generate large numerical tables, and analysis scripts consume the resulting .npy/binary arrays. There is no service layer, database, or networked component; the architecture is a collection of reproducible experiment pipelines centered on shared files.
14. Practical dependency boundaries
The Python side depends on Keras/H5Py and, for the difference-search demo, scikit-learn. The C++ side is isolated in cpp/ and requires a GCC-compatible compiler with C++14 and GCC builtins. That separation is important architecturally: high-cost combinatorial analysis is kept out of Python, while the deep-learning experiments remain in Keras/TensorFlow.
Main entry points: speck.py Speck core · net5_small.h5 Net weights · neural_difference_search.py Diff search · train_5_rounds.py Train 5r
Components 21
Python experiments
Neural distinguisher training, evaluation, attacks, and analysis scripts.
- Speck core · Shared Speck32/64 primitive and data-generation helpers used by all experiment paths.
speck.py - Simple Speck · Variant Speck helpers used by the simple-net training and preprocessing path.
simple_net/speck.py - Train 5r · Main script for training the 5-round neural distinguisher from scratch.
train_5_rounds.py - Train nets · General training driver for other round counts or model variants.
train_nets.py - Evaluate · Evaluates pretrained distinguishers in real-vs-random and real-difference settings.
eval.py - Key recovery · End-to-end neural key-recovery attack pipeline with 11-round and final 12-round variants.
test_key_recovery.py - Key rank · Computes rank statistics for the 9-round neural-distinguisher attack over different pair budgets.
key_rank.py - DDT rank · Key-rank experiment using a difference-distribution-table distinguisher instead of a learned model.
key_rank_ddt.py - Key nonuniformity · Analyzes whether distinguisher quality depends on the secret key and related wrong-key behavior.
key_nonuniformity.py - Key averaging · Implements key averaging and generates improved training data from its output.
key_averaging.py - Diff search · Trains a small distinguisher and searches for favorable input differences via few-shot optimization.
neural_difference_search.py
Model assets
Stored Keras models and architecture definitions used by the experiments.
- Simple model · JSON architecture for the simple 7-round pretrained network.
simple_net/simple_7r_model_preproc.json - ResNet JSON · Architecture definition for the single-block residual distinguisher.
single_block_resnet.json - Net weights · Pretrained H5 models for multiple round counts used by evaluation and attacks.
net5_small.h5 - Simple weights · Weights for the simple 7-round model.
simple_net/simple_7r_model_preproc_weights.h5
C++ analysis
Offline differential-analysis tools built separately from the Python pipeline.
- Speck analysis · C++ tool that validates differential behavior, transition probabilities, and search claims.
cpp/speck.cpp - Speck DDT · C++ tool that computes large round-by-round difference distributions for the chosen input difference.
cpp/speck_ddt.cpp
Precomputed data
Saved experiment outputs and measurement arrays consumed by analysis scripts.
- Rank traces · Stored 9-round attack rank traces for neural and DDT experiments.
supplementary_data/data_9r_attack/9r_attack_keyrank_32.npy - DDT traces · Stored 9-round DDT-based attack rank traces for multiple pair budgets.
supplementary_data/data_9r_ddt/ddt_attack_9rounds_keyrank32.npy - Key dependence · Stored 7-round key-dependence measurements used by the nonuniformity analysis.
supplementary_data/key_dependence/key_dependence_7r_tpr.npy - Train history · Learning history for the 5-round network, used for reproducing paper figures.
supplementary_data/learning_history_5r_net.p
Connections 25
- Speck core → Train 5r: generate data · Training consumes Speck-generated ciphertext pairs and labels.
- Speck core → Train nets: generate data · General training variants draw from the shared Speck data pipeline.
- Speck core → Evaluate: sample pairs · Evaluation uses the same cipher-level data generation foundation.
- Speck core → Key recovery: attack inputs · Key-recovery runs on ciphertext pairs derived from the core Speck layer.
- Speck core → Key rank: attack inputs · Rank experiments depend on Speck pair generation.
- Speck core → DDT rank: attack inputs · DDT-based rank experiments still operate on Speck pair data.
- Speck core → Key averaging: synthesize data · Key averaging produces improved training data from Speck samples.
- Simple Speck → Diff search: preprocess · The difference-search demo uses the simple Speck helper path for its smaller model workflow.
- Simple model → Diff search: load topology · The search pipeline trains and evaluates against the simple-network architecture.
- ResNet JSON → Net weights: define model · Architecture definitions pair with stored Keras weights.
- Simple model → Simple weights: define model · JSON topology and weights together form the simple pretrained network.
- Net weights → Evaluate: load model · Evaluation consumes pretrained distinguishers from H5 artifacts.
- Simple weights → Evaluate: load model · Simple-network evaluation reuses the stored pretrained weights.
- Net weights → Key recovery: score pairs · The attack pipeline relies on learned distinguishers to rank candidate subkeys.
- Net weights → Key rank: score pairs · Neural rank experiments use the pretrained models as the distinguisher.
- Net weights → Key nonuniformity: measure bias · Nonuniformity analysis probes model behavior across keys.
- Rank traces → Key rank: reference data · Saved rank traces support reporting and reproduction.
- DDT traces → DDT rank: reference data · Stored DDT traces support the table-based rank experiments.
- Key dependence → Key nonuniformity: reference data · Key-dependence measurements feed the analysis.
- Train history → Train 5r: record history · Training history captures the 5-round network learning curve.
- Speck analysis → Speck DDT: shared analysis base · Both C++ tools belong to the offline differential-analysis toolchain.
- Speck analysis → DDT rank: validate claims · C++ analysis underpins the non-neural differential experiments.
- Speck DDT → DDT traces: write tables · The DDT generator writes large transition tables consumed later by Python.
- Key averaging → Train 5r: improve training · Averaged or enhanced samples can be fed back into network training.
- Diff search → Train nets: search variants · Search results can inform additional training runs or variant models.