# agohr/deep_speck architecture

> Architecture diagram of the GitHub repository agohr/deep_speck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agohr/deep_speck
- Repository: https://github.com/agohr/deep_speck

## Overview

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`](https://github.com/agohr/deep_speck/blob/master/speck.py) (Speck core), [`net5_small.h5`](https://github.com/agohr/deep_speck/blob/master/net5_small.h5) (Net weights), [`neural_difference_search.py`](https://github.com/agohr/deep_speck/blob/master/neural_difference_search.py) (Diff search), [`train_5_rounds.py`](https://github.com/agohr/deep_speck/blob/master/train_5_rounds.py) (Train 5r)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python experiments"]
  node_speck_core["Speck core<br/>cipher/data-gen<br/>[speck.py]"]
  node_simple_speck["Simple Speck<br/>cipher helper<br/>[speck.py]"]
  node_train_5r["Train 5r<br/>training entrypoint<br/>[train_5_rounds.py]"]
  node_train_nets["Train nets<br/>training driver<br/>[train_nets.py]"]
  node_eval["Evaluate<br/>benchmarking<br/>[eval.py]"]
  node_key_recovery["Key recovery<br/>attack demo"]
  node_key_rank["Key rank<br/>attack analysis<br/>[key_rank.py]"]
  node_key_rank_ddt["DDT rank<br/>attack analysis<br/>[key_rank_ddt.py]"]
  node_key_nonuniformity["Key nonuniformity<br/>analysis"]
  node_key_averaging["Key averaging<br/>preprocessing<br/>[key_averaging.py]"]
  node_diff_search["Diff search<br/>exploration"]
end

subgraph group_assets["Model assets"]
  node_simple_model["Simple model<br/>keras topology"]
  node_resnet_json["ResNet JSON<br/>keras topology"]
  node_pretrained_nets[("Net weights<br/>keras weights<br/>[net5_small.h5]")]
  node_simple_weights[("Simple weights<br/>keras weights")]
end

subgraph group_cpp["C++ analysis"]
  node_speck_cpp["Speck analysis<br/>cpp tool<br/>[speck.cpp]"]
  node_speck_ddt_cpp["Speck DDT<br/>cpp tool<br/>[speck_ddt.cpp]"]
end

subgraph group_data["Precomputed data"]
  node_supp_rank["Rank traces<br/>saved experiment data"]
  node_supp_ddt["DDT traces<br/>saved experiment data"]
  node_supp_keydep["Key dependence<br/>saved experiment data"]
  node_supp_history["Train history<br/>saved experiment data"]
end

node_speck_core -->|"generate data"| node_train_5r
node_speck_core -->|"generate data"| node_train_nets
node_speck_core -->|"sample pairs"| node_eval
node_speck_core -->|"attack inputs"| node_key_recovery
node_speck_core -->|"attack inputs"| node_key_rank
node_speck_core -->|"attack inputs"| node_key_rank_ddt
node_speck_core -->|"synthesize data"| node_key_averaging
node_simple_speck -->|"preprocess"| node_diff_search
node_simple_model -->|"load topology"| node_diff_search
node_resnet_json -->|"define model"| node_pretrained_nets
node_simple_model -->|"define model"| node_simple_weights
node_pretrained_nets -->|"load model"| node_eval
node_simple_weights -->|"load model"| node_eval
node_pretrained_nets -->|"score pairs"| node_key_recovery
node_pretrained_nets -->|"score pairs"| node_key_rank
node_pretrained_nets -->|"measure bias"| node_key_nonuniformity
node_supp_rank -->|"reference data"| node_key_rank
node_supp_ddt -->|"reference data"| node_key_rank_ddt
node_supp_keydep -->|"reference data"| node_key_nonuniformity
node_supp_history -->|"record history"| node_train_5r
node_speck_cpp -->|"shared analysis base"| node_speck_ddt_cpp
node_speck_cpp -.->|"validate claims"| node_key_rank_ddt
node_speck_ddt_cpp -->|"write tables"| node_supp_ddt
node_key_averaging -.->|"improve training"| node_train_5r
node_diff_search -.->|"search variants"| node_train_nets

click node_speck_core "https://github.com/agohr/deep_speck/blob/master/speck.py"
click node_simple_speck "https://github.com/agohr/deep_speck/blob/master/simple_net/speck.py"
click node_train_5r "https://github.com/agohr/deep_speck/blob/master/train_5_rounds.py"
click node_train_nets "https://github.com/agohr/deep_speck/blob/master/train_nets.py"
click node_eval "https://github.com/agohr/deep_speck/blob/master/eval.py"
click node_key_recovery "https://github.com/agohr/deep_speck/blob/master/test_key_recovery.py"
click node_key_rank "https://github.com/agohr/deep_speck/blob/master/key_rank.py"
click node_key_rank_ddt "https://github.com/agohr/deep_speck/blob/master/key_rank_ddt.py"
click node_key_nonuniformity "https://github.com/agohr/deep_speck/blob/master/key_nonuniformity.py"
click node_key_averaging "https://github.com/agohr/deep_speck/blob/master/key_averaging.py"
click node_diff_search "https://github.com/agohr/deep_speck/blob/master/neural_difference_search.py"
click node_simple_model "https://github.com/agohr/deep_speck/blob/master/simple_net/simple_7r_model_preproc.json"
click node_resnet_json "https://github.com/agohr/deep_speck/blob/master/single_block_resnet.json"
click node_pretrained_nets "https://github.com/agohr/deep_speck/blob/master/net5_small.h5"
click node_simple_weights "https://github.com/agohr/deep_speck/blob/master/simple_net/simple_7r_model_preproc_weights.h5"
click node_speck_cpp "https://github.com/agohr/deep_speck/blob/master/cpp/speck.cpp"
click node_speck_ddt_cpp "https://github.com/agohr/deep_speck/blob/master/cpp/speck_ddt.cpp"
click node_supp_rank "https://github.com/agohr/deep_speck/blob/master/supplementary_data/data_9r_attack/9r_attack_keyrank_32.npy"
click node_supp_ddt "https://github.com/agohr/deep_speck/blob/master/supplementary_data/data_9r_ddt/ddt_attack_9rounds_keyrank32.npy"
click node_supp_keydep "https://github.com/agohr/deep_speck/blob/master/supplementary_data/key_dependence/key_dependence_7r_tpr.npy"
click node_supp_history "https://github.com/agohr/deep_speck/blob/master/supplementary_data/learning_history_5r_net.p"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_speck_core,node_simple_speck,node_train_5r,node_train_nets,node_eval,node_key_recovery,node_key_rank,node_key_rank_ddt,node_key_nonuniformity,node_key_averaging,node_diff_search toneBlue
class node_simple_model,node_resnet_json,node_pretrained_nets,node_simple_weights toneAmber
class node_speck_cpp,node_speck_ddt_cpp toneMint
class node_supp_rank,node_supp_ddt,node_supp_keydep,node_supp_history toneRose
```

## Components

### Python experiments

Neural distinguisher training, evaluation, attacks, and analysis scripts.

- [Speck core](https://github.com/agohr/deep_speck/blob/master/speck.py): cipher/data-gen · Shared Speck32/64 primitive and data-generation helpers used by all experiment paths. · `speck.py`
- [Simple Speck](https://github.com/agohr/deep_speck/blob/master/simple_net/speck.py): cipher helper · Variant Speck helpers used by the simple-net training and preprocessing path. · `simple_net/speck.py`
- [Train 5r](https://github.com/agohr/deep_speck/blob/master/train_5_rounds.py): training entrypoint · Main script for training the 5-round neural distinguisher from scratch. · `train_5_rounds.py`
- [Train nets](https://github.com/agohr/deep_speck/blob/master/train_nets.py): training driver · General training driver for other round counts or model variants. · `train_nets.py`
- [Evaluate](https://github.com/agohr/deep_speck/blob/master/eval.py): benchmarking · Evaluates pretrained distinguishers in real-vs-random and real-difference settings. · `eval.py`
- [Key recovery](https://github.com/agohr/deep_speck/blob/master/test_key_recovery.py): attack demo · End-to-end neural key-recovery attack pipeline with 11-round and final 12-round variants. · `test_key_recovery.py`
- [Key rank](https://github.com/agohr/deep_speck/blob/master/key_rank.py): attack analysis · Computes rank statistics for the 9-round neural-distinguisher attack over different pair budgets. · `key_rank.py`
- [DDT rank](https://github.com/agohr/deep_speck/blob/master/key_rank_ddt.py): attack analysis · Key-rank experiment using a difference-distribution-table distinguisher instead of a learned model. · `key_rank_ddt.py`
- [Key nonuniformity](https://github.com/agohr/deep_speck/blob/master/key_nonuniformity.py): analysis · Analyzes whether distinguisher quality depends on the secret key and related wrong-key behavior. · `key_nonuniformity.py`
- [Key averaging](https://github.com/agohr/deep_speck/blob/master/key_averaging.py): preprocessing · Implements key averaging and generates improved training data from its output. · `key_averaging.py`
- [Diff search](https://github.com/agohr/deep_speck/blob/master/neural_difference_search.py): exploration · 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](https://github.com/agohr/deep_speck/blob/master/simple_net/simple_7r_model_preproc.json): keras topology · JSON architecture for the simple 7-round pretrained network. · `simple_net/simple_7r_model_preproc.json`
- [ResNet JSON](https://github.com/agohr/deep_speck/blob/master/single_block_resnet.json): keras topology · Architecture definition for the single-block residual distinguisher. · `single_block_resnet.json`
- [Net weights](https://github.com/agohr/deep_speck/blob/master/net5_small.h5): keras weights · Pretrained H5 models for multiple round counts used by evaluation and attacks. · `net5_small.h5`
- [Simple weights](https://github.com/agohr/deep_speck/blob/master/simple_net/simple_7r_model_preproc_weights.h5): keras 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](https://github.com/agohr/deep_speck/blob/master/cpp/speck.cpp): cpp tool · C++ tool that validates differential behavior, transition probabilities, and search claims. · `cpp/speck.cpp`
- [Speck DDT](https://github.com/agohr/deep_speck/blob/master/cpp/speck_ddt.cpp): cpp tool · 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](https://github.com/agohr/deep_speck/blob/master/supplementary_data/data_9r_attack/9r_attack_keyrank_32.npy): saved experiment data · Stored 9-round attack rank traces for neural and DDT experiments. · `supplementary_data/data_9r_attack/9r_attack_keyrank_32.npy`
- [DDT traces](https://github.com/agohr/deep_speck/blob/master/supplementary_data/data_9r_ddt/ddt_attack_9rounds_keyrank32.npy): saved experiment data · Stored 9-round DDT-based attack rank traces for multiple pair budgets. · `supplementary_data/data_9r_ddt/ddt_attack_9rounds_keyrank32.npy`
- [Key dependence](https://github.com/agohr/deep_speck/blob/master/supplementary_data/key_dependence/key_dependence_7r_tpr.npy): saved experiment data · Stored 7-round key-dependence measurements used by the nonuniformity analysis. · `supplementary_data/key_dependence/key_dependence_7r_tpr.npy`
- [Train history](https://github.com/agohr/deep_speck/blob/master/supplementary_data/learning_history_5r_net.p): saved experiment data · Learning history for the 5-round network, used for reproducing paper figures. · `supplementary_data/learning_history_5r_net.p`

## Connections

- 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.
