diff --git a/.delivery/d1.tgz b/.delivery/d1.tgz
deleted file mode 100644
index 4f8a12c..0000000
Binary files a/.delivery/d1.tgz and /dev/null differ
diff --git a/.delivery/d2.tgz b/.delivery/d2.tgz
deleted file mode 100644
index d275f4a..0000000
Binary files a/.delivery/d2.tgz and /dev/null differ
diff --git a/.delivery/d3.tgz b/.delivery/d3.tgz
deleted file mode 100644
index ea2704c..0000000
Binary files a/.delivery/d3.tgz and /dev/null differ
diff --git a/.delivery/d4.tgz b/.delivery/d4.tgz
deleted file mode 100644
index 3bc4d37..0000000
Binary files a/.delivery/d4.tgz and /dev/null differ
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..efdcf1a
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,27 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+
+[*.{v,sv}]
+indent_size = 4
+
+[*.{html,css}]
+indent_size = 2
+
+[*.{yml,yaml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[{Makefile,*.mk}]
+indent_style = tab
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..2fb177a
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,63 @@
+name: Bug report
+description: Report something that is not working
+labels:
+- bug
+body:
+- type: textarea
+ id: what
+ attributes:
+ label: What happened?
+ description: Describe the bug and what you expected instead.
+ validations:
+ required: true
+- type: textarea
+ id: steps
+ attributes:
+ label: Steps to reproduce
+ description: Numbered steps, as exact as possible.
+ validations:
+ required: true
+- type: dropdown
+ id: lab
+ attributes:
+ label: Lab
+ options:
+ - 1 LFSR hop generator
+ - 2 PRNG graveyard
+ - 3 CPA of SipHash
+ - 4 Masking
+ - 5 Fault injection / TMR
+ - 6 Trojan / PUF
+ - Trace explorer (HTML)
+ - Grader / tooling
+ validations:
+ required: true
+- type: input
+ id: env
+ attributes:
+ label: Operating system and Python version
+ description: e.g. Ubuntu 24.04, Python 3.12.3 (`python3 --version`).
+ validations:
+ required: true
+- type: input
+ id: tools
+ attributes:
+ label: Other tool versions
+ description: Browser + Playwright version for the explorer, or RTL simulator versions if relevant.
+ validations:
+ required: false
+- type: input
+ id: commit
+ attributes:
+ label: Commit
+ description: Output of `git rev-parse --short HEAD`.
+ validations:
+ required: true
+- type: textarea
+ id: logs
+ attributes:
+ label: Logs or output
+ description: Paste relevant output. It will be formatted as code. Remove personal data first.
+ render: shell
+ validations:
+ required: false
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..3ba13e0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1 @@
+blank_issues_enabled: false
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..6b42b9e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,33 @@
+name: Feature request
+description: Suggest an improvement
+labels:
+- enhancement
+body:
+- type: textarea
+ id: problem
+ attributes:
+ label: Problem or motivation
+ description: What are you trying to do that is hard today?
+ validations:
+ required: true
+- type: textarea
+ id: proposal
+ attributes:
+ label: Proposed solution
+ description: Describe what you would like to see.
+ validations:
+ required: true
+- type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives considered
+ description: Other approaches you thought about.
+ validations:
+ required: false
+- type: textarea
+ id: lab
+ attributes:
+ label: Lab or exercise
+ description: Which lab it extends, learning objective and expected duration.
+ validations:
+ required: false
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..e2347a8
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: github-actions
+ directory: /
+ schedule:
+ interval: weekly
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..8691eb9
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,16 @@
+## Summary
+
+What does this change and why?
+
+## Checklist
+
+- [ ] `python -m rtlseclab.check` passes (all solutions pass their graders)
+- [ ] `python -m rtlseclab.check --starters` still shows every starter failing cleanly
+- [ ] `python -m unittest tests.test_graders` passes
+- [ ] Copied code carries an ORIGIN header
+- [ ] Documentation updated where behaviour changed
+- [ ] No secrets, keys or personal data committed
+
+## Test notes
+
+How was this verified? Paste commands and results, or write "not run".
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..0b5ccd7
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,46 @@
+name: CI
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ kit:
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ["3.10", "3.13"]
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python-version }}
+ cache: pip
+ - run: python -m pip install -r requirements.txt
+ - name: Every solution passes its grader; every starter fails cleanly
+ run: python -m rtlseclab.check --starters
+ - name: Grader tests (starters in sync, mutants caught, standalone, ORIGIN headers)
+ run: python -m unittest -v tests.test_graders
+ - name: Student export contains no solutions
+ run: |
+ python -m rtlseclab.tools.make_student_kit "$RUNNER_TEMP/student"
+ ! find "$RUNNER_TEMP/student" -name 'solution.py' -o -name 'answer_key.md' | grep .
+ cd "$RUNNER_TEMP/student" && ! python labs/lab1_lfsr_break/grader.py labs/lab1_lfsr_break/starter.py
+
+ seed-robustness:
+ # Tolerance bands must hold for seed streams other than the default one. Slow, so not on every push.
+ if: github.event_name == 'workflow_dispatch'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.13"
+ - run: python -m pip install -r requirements.txt
+ - run: python tests/test_robustness.py 20 4
diff --git a/.gitignore b/.gitignore
index 1bd194b..8543304 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,3 +46,12 @@ dist/
*.wlf
*.fsdb
*.vpd
+
+# --- RTL-Sec-Lab ---
+# student hand-out export (python -m rtlseclab.tools.make_student_kit)
+dist/
+# delivery bundles duplicate tracked files
+.delivery/
+*.tgz
+.ruff_cache/
+.mypy_cache/
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 0000000..d53f292
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: If you use this software, please cite it as below.
+title: RTL-Sec-Lab
+type: software
+authors:
+ - given-names: Kavin
+ family-names: K K
+ alias: Kavin-Re
+repository-code: https://github.com/Kavin-Re/RTL-Sec-Lab
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..2fb1c85
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,32 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). The full text at that link applies; this is a summary.
+
+## Our pledge
+
+We pledge to make participation in RTL-Sec-Lab a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Expected behaviour
+
+- Be respectful, welcoming and constructive.
+- Accept feedback gracefully and give it kindly.
+- Focus on what is best for the project and community.
+
+## Unacceptable behaviour
+
+- Harassment, insults, trolling, or personal or political attacks.
+- Sexualized language or imagery, and unwelcome attention.
+- Publishing others' private information without permission.
+- Other conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Enforcement
+
+Maintainers may remove, edit or reject comments, commits, issues and other contributions that violate this code, and may ban contributors for behaviour they deem harmful.
+
+## Reporting
+
+To report a problem, open an issue at https://github.com/Kavin-Re/RTL-Sec-Lab/issues without including sensitive details, and ask for private follow-up. Maintainers will respond and handle reports with discretion.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..2e2be82
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,33 @@
+# Contributing to RTL-Sec-Lab
+
+Thanks for your interest. RTL-Sec-Lab is a simulation-only workshop kit on the hardware security of a small keyed hop/PRF engine. Read `docs/facilitator_guide.md` first.
+
+## Getting started
+
+Python 3 and numpy; no network access is needed.
+
+```
+python -m rtlseclab.check # all solutions through all graders
+python -m rtlseclab.check --starters # every starter must FAIL cleanly
+python labs/lab3_power_cpa/grader.py labs/lab3_power_cpa/starter.py
+```
+
+## Testing
+
+```
+python -m unittest tests.test_graders
+python tests/test_explorer.py # needs Playwright; skipped otherwise
+```
+
+Starters are generated from solutions (see the README); edit the solution, then regenerate. Copied code must carry an ORIGIN header.
+
+## Pull requests
+
+- Open an issue first for larger changes.
+- Keep PRs focused and fill in the pull request template.
+- Follow `.editorconfig` and match the style of surrounding code.
+- Say which simulator and tool versions you used for RTL changes.
+
+## Conduct
+
+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
diff --git a/README.md b/README.md
index d7602f7..232e746 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,151 @@
# RTL-Sec-Lab
-A self-contained workshop kit on the hardware security of a small keyed hop/PRF engine (own design, **simulation only**). Python + numpy only, no network, no imports from any other repository.
-
-| Lab | Topic | Minutes |
-|---|---|---|
-| 1 | Breaking the 16-bit LFSR hop generator | 25 |
-| 2 | The PRNG graveyard (LCG, Mersenne Twister, xorshift, context predictor) | 20 |
-| 3 | Correlation power analysis of the SipHash engine | 30 |
-| 4 | Masking and its limits (first vs second order, t-test) | 25 |
-| 5 | Fault injection and the cost of TMR | 20 |
-| 6 | Trojan detection and a PUF key source | 25 |
-
-Quick start
+**A three-hour, six-lab workshop kit on the hardware security of a small keyed frequency-hop engine: breaking weak generators, power analysis, masking, fault injection, trojans and PUFs. Every lab has a starter, a reference solution and a deterministic auto-grader.**
+
+[](https://github.com/Kavin-Re/RTL-Sec-Lab/actions/workflows/ci.yml)
+
+
+
+
+> **Scope.** Everything is simulation of the author's own design. There is no device, no measured
+> trace, no radio and no real exploit. Leakage, fault, trojan and PUF behaviour come from simple
+> assumed models, and each handout says so. The Verilog in `rtl/` is for reading; the kit does not
+> simulate it.
+
+> **This repository contains the solutions.** It is the facilitator's copy. Give students the
+> export described under [Running a workshop](#running-a-workshop).
+
+## The labs
+
+The running example is a hop engine that outputs `SipHash-2-4(key, slot) mod 13`, contrasted with
+the 16-bit LFSR it replaces.
+
+| # | Lab | What students build | What the reference solution shows |
+|---|---|---|---|
+| 1 | Breaking the 16-bit LFSR hop generator | Candidate elimination over all 65,535 states | State pinned down after 8.33 hops on average; each hop shrinks the candidate set about 4x, not 13x |
+| 2 | The PRNG graveyard | LCG state recovery, Mersenne Twister cloning, a GF(2) solver for xorshift, a context predictor | LCG-24 predicted after 7 hops, xorshift-32 after 9, MT19937 after 624 raw 32-bit outputs; keyed schedules stay at chance |
+| 3 | Correlation power analysis | Hamming-weight hypotheses, Pearson correlation, two-stage divide and conquer with carry | Full 128-bit key from 200 simulated traces at sigma = 2; trace count grows 4x when the noise doubles |
+| 4 | Masking and its limits | 2-share Boolean masking, first- and second-order CPA, fixed-vs-random Welch t-test | First-order attack fails on masked traces, second-order succeeds with more traces; a share-recombining register undoes the masking |
+| 5 | Fault injection and the cost of TMR | Majority voter, exact and Monte Carlo TMR failure probability, area trade-off | State-only TMR costs about 53 % in the gate-equivalent proxy, full-engine TMR about 200 %; a common-mode flip passes the voter |
+| 6 | Trojan detection and a PUF key source | Chi-square alarm, CUSUM, PUF uniqueness and reliability, fuzzy extractor | CUSUM flags a 3.1 % output bias after 14 windows on average, a single-window alarm after 24; a layout gradient ruins PUF uniqueness until it is removed |
+
+Labs 1 to 6 are budgeted at 25, 20, 30, 25, 20 and 25 minutes. The numbers in the right-hand column
+are the deterministic output of `python -m rtlseclab.check` with the default seeds.
+
+```mermaid
+flowchart LR
+ subgraph KIT["Facilitator repository"]
+ SOL["labs/labN/solution.py
answer_key.md"]
+ GR["labs/labN/grader.py
expected.json (tolerance bands)"]
+ CORE["rtlseclab/core/
SipHash, LFSR, PRNGs, leakage,
fault, trojan, PUF models"]
+ RTL["rtl/*.v (reading only)"]
+ end
+ SOL -->|make_starters| ST["labs/labN/starter.py
TODO stubs"]
+ KIT -->|make_student_kit| STU["Student copy
no solutions, no answer keys"]
+ ST --> G{{"grader: PASS / FAIL per task"}}
+ GR --> G
+ CORE --> G
+ CORE -->|build_explorer| EX["explorer/trace_explorer.html
offline CPA demo"]
```
-python -m rtlseclab.check # all solutions through all graders
-python -m rtlseclab.check --starters # also confirm every starter FAILs cleanly
-python labs/lab3_power_cpa/grader.py labs/lab3_power_cpa/starter.py
-python -m unittest tests.test_graders
-python tests/test_explorer.py # needs playwright; skipped otherwise
-open explorer/trace_explorer.html # offline, single file
+
+## Quick start
+
+```bash
+git clone https://github.com/Kavin-Re/RTL-Sec-Lab.git && cd RTL-Sec-Lab
+python -m pip install -r requirements.txt # numpy
+
+python -m rtlseclab.check # every solution through every grader
+python -m rtlseclab.check --starters # ...and confirm every starter fails cleanly
+python labs/lab3_power_cpa/grader.py labs/lab3_power_cpa/solution.py
+```
+
+Expected last line of the check: `KIT CHECK: 39/39 solution tasks PASS across 6 labs`.
+
+A grader run looks like this:
+
+```console
+$ python labs/lab3_power_cpa/grader.py labs/lab3_power_cpa/solution.py
+PASS T3 stage-1 CPA recovers k1 [5/5 keys, peak r = 0.580]
+PASS T4 stage-2 CPA recovers k0 (carry, low byte first) [5/5 keys, k0 recovered given k1]
+PASS T5 success_rate vs noise and N [success: s2/N50 0.00, s2/N200 1.00, s4/N800 1.00]
+PASS T6 min_traces scales with sigma^2 [min traces: sigma 2 -> 200, sigma 4 -> 800 (x4.0)]
+...
+SUMMARY: 7/7 PASS
```
-Read `docs/facilitator_guide.md` first. Each lab folder has `handout.md`, `starter.py`, `solution.py`, `grader.py`, `expected.json`, `answer_key.md`. Starters are generated from solutions: `python -m rtlseclab.tools.make_starters`. The explorer is generated by `python -m rtlseclab.tools.build_explorer`.
-Copied code carries an ORIGIN header (file and repository it came from). All models are assumptions; see the limits section of the facilitator guide.
+`explorer/trace_explorer.html` is a single offline page for labs 3 and 4: it runs the CPA in the
+browser on embedded simulated traces and shows why masking defeats the first-order attack.
+
+
+
+## Running a workshop
+
+1. Read [`docs/facilitator_guide.md`](docs/facilitator_guide.md): setup, a minute-by-minute plan,
+ common mistakes per lab, and the list of things the kit does not model.
+2. Export the student copy and distribute that, not this repository:
+
+ ```bash
+ python -m rtlseclab.tools.make_student_kit # -> dist/rtl-sec-lab-student/
+ ```
+
+ It contains the handouts, starters, graders, the models, the RTL and the explorer. It leaves
+ out `solution.py`, `answer_key.md`, the facilitator guide and the kit self-tests.
+3. Students fill in the TODOs of `labs/labN_*/starter.py` and grade themselves with
+ `python labs/labN_*/grader.py labs/labN_*/starter.py`.
+
+**The graders are for self-checking, not for assessment.** They compare student code against
+reference models in `rtlseclab/core/`, which therefore ship with the student copy; a student who
+wants to can call those directly. The seeds are fixed; `RTLSECLAB_SEED_SHIFT=k` shifts them if you
+suspect hard-coded outputs. And because this repository is public, the solutions are one search
+away. See the note on publishing below.
+
+## How the kit checks itself
+
+| Check | Command |
+|---|---|
+| All 39 solution tasks pass; all starters fail with "not implemented yet" and never crash the grader | `python -m rtlseclab.check --starters` |
+| Starters are regenerated from the solutions and in sync | `python -m rtlseclab.tools.make_starters --check` |
+| Mutation tests: six deliberately broken solutions each fail the intended task | `python -m unittest tests.test_graders` |
+| Tolerance bands hold for 20 different seed streams | `python tests/test_robustness.py 20 4` (several minutes) |
+| The explorer's JavaScript CPA agrees with a NumPy CPA on the same data | `python tests/test_explorer.py` (needs Playwright; rewrites `tests/screens/`) |
+
+## Repository layout
+
+```
+labs/labN_*/ handout.md starter.py solution.py grader.py expected.json answer_key.md
+rtlseclab/core/ the models (each file names the FHSS-Link file it was copied from)
+rtlseclab/ grading.py (harness), check.py (kit check), tools/ (starters, student kit, explorer)
+rtl/ hop_lfsr.v, hop_keyed.v (reading only)
+explorer/ trace_explorer.html (generated from template.html)
+docs/ facilitator_guide.md, MODEL_NOTES.md, known_issues.md
+tests/ grader tests, explorer test, seed-robustness script
+```
+
+## Limitations
+
+- **No measurements.** Power traces are Hamming weight or distance of one byte plus Gaussian
+ noise: no alignment, jitter, glitches or coupling. Masking is modelled at share-byte level only.
+- **The CPA labs use uniformly random 64-bit messages.** The real engine hashes a slot counter.
+ With consecutive slots, the first-round attack of Lab 3 recovers only the key bytes aligned with
+ counter bytes that change: 1 of 8 bytes of each key half at 300 traces and 2 of 8 at 70,000 in
+ this model. The labs teach the method; they are not an end-to-end break of a counter-mode engine.
+- **Faults are abstract bit flips** in a receiver-side register model. No physical mechanism, no
+ datapath, voter or transmit-side faults.
+- **Area figures are a gate-equivalent proxy** built from assumed cell areas, not synthesis results.
+- **The Python hop model and `rtl/hop_keyed.v` are not bit-identical.** They share the SipHash
+ digest but map it to a channel differently. See [`docs/MODEL_NOTES.md`](docs/MODEL_NOTES.md).
+- **Trojan and PUF models are abstractions** and prove nothing about any real chip.
+- Lab durations are the author's plan. This repository holds no record of the kit being run with an audience.
+- No citations are included beyond named classic ideas. Look them up before quoting.
+
+## Related projects
+
+The models and RTL are copied from the silicon-security experiments in
+[FHSS-Link](https://github.com/Kavin-Re/FHSS-Link) (each file carries an ORIGIN header) and made
+standalone; nothing is imported from that repository. [HopBench](https://github.com/Kavin-Re/HopBench)
+turns the attacks of labs 1 and 2 into a scoring benchmark.
+
+## License
+
+No license file has been added yet, so default copyright applies. A workshop kit is only useful if
+others may reuse it, so adding a license is the first item on the to-do list. Until then, please ask.
diff --git a/docs/MODEL_NOTES.md b/docs/MODEL_NOTES.md
new file mode 100644
index 0000000..a51b720
--- /dev/null
+++ b/docs/MODEL_NOTES.md
@@ -0,0 +1,41 @@
+# Model notes: how the Python models relate to the RTL in `rtl/`
+
+The kit does not simulate RTL. The two Verilog files are included for reading, so that the labs can point at real
+registers and adders. This note states exactly where the Python models in `rtlseclab/core/` match that RTL and where
+they do not.
+
+## `rtl/hop_lfsr.v` and `rtlseclab/core/lfsr.py`: same sequence
+
+Both implement x^16 + x^14 + x^13 + x^11 + 1 as a right-shifting Fibonacci LFSR (feedback `s0 ^ s2 ^ s3 ^ s5` enters at
+bit 15), step the state first and then output `state mod M`, reset to `0xACE1`, and map seed 0 to 1.
+`lfsr_schedule()` is written to produce the same channel sequence as the RTL. That equivalence was established in the
+FHSS-Link repository the files were copied from; this kit contains no RTL simulation that re-checks it.
+
+## `rtl/hop_keyed.v` and `rtlseclab/core/siphash.py`: same PRF, different channel mapping
+
+| | RTL (`hop_keyed.v`) | Python model |
+|---|---|---|
+| PRF | SipHash-2-4, one SipRound per clock | SipHash-2-4 (`siphash24`, `siphash24_u64`) |
+| Message | `{retry[7:0], slot[55:0]}`, 8 bytes | 64-bit slot counter, 8 bytes little-endian |
+| Digest to channel | Lemire multiply-shift on 32-bit chunks of the digest, with rejection (unbiased); on rejection of all chunks, `retry++` and re-hash | `digest mod 13` |
+| Slot counter | 56 bits, auto-increment | 64-bit in the hop models, 32-bit register in the fault model |
+
+Consequences:
+
+- For slots below 2^56 and `retry = 0` the two compute the **same 64-bit digest**. They then map it to a channel
+ differently, so the **channel sequences are not equal**. Do not use the Python hops as test vectors for the RTL.
+- `digest mod 13` has a modulo bias of at most 13 / 2^64 per channel, far below anything the labs can measure.
+ The RTL removes even that by rejection.
+- What the labs teach does not depend on the mapping: the leakage points of labs 3 and 4 (`v3 = k1 ^ C3 ^ m` and the
+ first addition `v2 + v3`) are before the reduction; the state registers faulted in lab 5 (key, slot counter, FSM,
+ output register) exist in both; and the output statistics used in labs 1, 2 and 6 are uniform over 13 channels in both.
+
+## What is modelled, in one table
+
+| Lab | Model | Assumption |
+|---|---|---|
+| 3, 4 | `core/leakage.py` | Each trace sample is the Hamming weight (or distance) of one byte plus Gaussian noise. No alignment, jitter, glitches or coupling. Masking is at share-byte level. |
+| 5 | `core/faultsim.py` | Faults are bit flips or sequencing errors in receiver-side registers. No physical mechanism, no datapath or voter faults. |
+| 5 | `core/ge_model.py` | Gate-equivalent proxy from assumed per-cell areas. Not a synthesis result. |
+| 6 | `core/trojan.py` | Trigger counter plus output mux, observed only through the channel sequence. |
+| 6 | `core/puf.py` | Ring-oscillator frequencies = layout gradient + Gaussian process variation + read noise + linear temperature term. |
diff --git a/docs/facilitator_guide.md b/docs/facilitator_guide.md
index 0539f58..1e622e5 100644
--- a/docs/facilitator_guide.md
+++ b/docs/facilitator_guide.md
@@ -7,7 +7,7 @@ A self-contained kit on the hardware security of a small keyed hop/PRF engine (o
- Copy the kit folder, `cd` into it, run `python -m rtlseclab.check`. Expected last line: `KIT CHECK: 39/39 solution tasks PASS across 6 labs` (about 30-60 s on a laptop).
- Students work in `labs/labN_*/starter.py`; grade with `python labs/labN_*/grader.py labs/labN_*/starter.py`. Each grader prints PASS/FAIL per task and exits non-zero on any FAIL. Graders are deterministic (fixed seeds); `RTLSECLAB_SEED_SHIFT=k` shifts all seeds if you suspect a student hard-coded outputs.
- Open `explorer/trace_explorer.html` in any browser (single file, offline) for Labs 3-4.
-- Hand out each `handout.md`; keep `solution.py` and `answer_key.md` back.
+- Hand out each `handout.md`; keep `solution.py` and `answer_key.md` back. `python -m rtlseclab.tools.make_student_kit` writes a copy of the kit without them to `dist/rtl-sec-lab-student/`. The repository itself contains the solutions, so point students at that export, not at the repository.
## Timing (180 minutes)
| Time | Block | Notes |
@@ -34,6 +34,7 @@ If time runs short drop the stretch tasks (marked "(stretch)" in the grader outp
## What the kit does not do (say this out loud)
- Leakage is an assumed Hamming-weight/Hamming-distance model with Gaussian noise; no alignment, jitter, or real measurement. Masking is modelled at the share-byte level only (no glitches, coupling or routing).
+- Labs 3 and 4 attack traces taken with uniformly random 64-bit messages. The engine's real input is a slot counter; with consecutive slots the first-round CPA of Lab 3 recovers only the key bytes aligned with counter bytes that change (1 of 8 bytes of each key half at 300 traces, 2 of 8 at 70,000; see `docs/known_issues.md`). The labs teach the method, not an end-to-end break of a counter-mode engine.
- Faults are abstract bit flips in a receiver model; TX-side faults, datapath faults, voter faults and common-mode faults are outside the model except the T6 demonstration.
- Area numbers are a proxy with assumed cell areas, not synthesis results.
- Trojan and PUF models are our own abstractions; the kit proves nothing about any real chip.
diff --git a/docs/known_issues.md b/docs/known_issues.md
index 603b11e..3e73af7 100644
--- a/docs/known_issues.md
+++ b/docs/known_issues.md
@@ -1,5 +1,26 @@
# Known issues
-1. **Lab 4 T5 band is too tight for one seed stream (found by tests/test_robustness.py, shift 7).** `second-order, N=3000, sigma=2` returned 5 of 8 bytes at `RTLSECLAB_SEED_SHIFT=7`; the accepted band is 6-8. With the default seeds (shift 0) and 19 of 20 shifts every task passes (`tests/robustness_result.txt`). Fix (not applied in this delivered copy because delivered files were write-protected): in `labs/lab4_masking/expected.json` change the T5 item `"lo": 6` to `"lo": 4`, and the same number in the `expected` text of the handout table (`6-8` -> `4-8`). Re-run `python tests/test_robustness.py 20 2`.
-2. Plotting is not part of the kit (no matplotlib); the explorer is the only visual.
-3. Timing figures in the facilitator guide come from a 2-core cloud machine; a laptop is similar.
+## Open
+
+1. **Labs 3 and 4 assume uniformly random messages.** The graders and the explorer generate traces with messages drawn
+ uniformly from all 64-bit values (`rand64`). The engine's real input is a slot counter. With consecutive slots only
+ the low counter bytes change, a constant message byte gives a constant Hamming-weight hypothesis, and the first-round
+ CPA cannot rank guesses for that key byte. Measured with `rtlseclab.core.leakage.cpa_attack` at sigma = 2 over 5 keys:
+ consecutive slots give 1 of 8 bytes of k1 (and of k0) at N = 300 and N = 5000 (one run reached 2), and 2 of 8 at
+ N = 70,000, against 8 of 8 with random messages at every N. The handout and the facilitator guide now say this. A
+ lab task on the counter case (and on what an attacker does about it) would close the gap.
+2. **The Python hop model is not bit-identical to `rtl/hop_keyed.v`** (same SipHash digest, different digest-to-channel
+ mapping). See `docs/MODEL_NOTES.md`. The kit contains no RTL simulation.
+3. **Graders are self-check tools, not assessment tools.** The reference models the graders compare against live in
+ `rtlseclab/core/` and ship with the student copy.
+4. `tests/test_explorer.py` rewrites the committed screenshots in `tests/screens/` every time it runs, so a local run
+ leaves the working tree dirty.
+5. Plotting is not part of the kit (no matplotlib); the explorer is the only visual.
+6. Timing figures in the facilitator guide come from a 2-core cloud machine.
+
+## Fixed
+
+- **Lab 4 T5 band was too tight for one seed stream** (found by `tests/test_robustness.py`, shift 7: second-order attack
+ at N = 3000, sigma = 2 returned 5 of 8 bytes against an accepted band of 6-8). The band is now 4-8 in
+ `labs/lab4_masking/expected.json` and in the handout table. `tests/robustness_result.txt` is the re-run after the
+ change: 20 of 20 seed shifts pass every task.
diff --git a/labs/lab3_power_cpa/handout.md b/labs/lab3_power_cpa/handout.md
index 8506348..89b2be9 100644
--- a/labs/lab3_power_cpa/handout.md
+++ b/labs/lab3_power_cpa/handout.md
@@ -6,6 +6,8 @@ Own design, simulation only. The traces come from an **assumed** leakage model (
**Target.** SipHash-2-4 on an 8-byte counter message m, first SipRound. Stage 1: v3 = k1 ^ C3 ^ m leaks HW of each byte of v3. Stage 2: s = (k0 ^ C2) + v3 leaks HW of each byte of s; with k1 known, v3 is known, and byte b of s depends on k0 byte b, v3 byte b and the carry from bytes 0..b-1. A trace has 16 samples (8 + 8).
+**Assumption to keep in mind.** The grader draws every message m uniformly at random from all 64-bit values, so every message byte varies. A real hop engine hashes a slot counter that counts up: over a few hundred hops only its lowest byte changes, and this first-round attack then recovers only the key bytes that line up with changing counter bytes (1 of 8 at 300 consecutive slots). Full-key recovery here is a property of the random-message setting.
+
**Tasks** (`python labs/lab3_power_cpa/grader.py labs/lab3_power_cpa/starter.py`)
T1 `hw8`. T2 `corr_cols` (Pearson per column, constant column gives 0). T3 `scores_stage1` + `recover_k1`. T4 `scores_stage2` + `recover_k0` (use the given `carry_in`). T5 `success_rate(sigma, N)` = fraction of full 128-bit keys recovered. T6 `min_traces(sigma)`. T7 (stretch) with Hamming-distance leakage, find the two best guesses for k0 byte 0.
diff --git a/labs/lab4_masking/expected.json b/labs/lab4_masking/expected.json
index cf76e97..be38ce1 100644
--- a/labs/lab4_masking/expected.json
+++ b/labs/lab4_masking/expected.json
@@ -8,7 +8,7 @@
{"task": "T4", "quantity": "fo_attack on masked traces, N=10000, sigma=1 (bytes right of 8; chance is 8/256)", "expected": 0, "lo": 0, "hi": 2},
{"task": "T4", "quantity": "so_attack on masked traces, N=10000, sigma=2", "expected": 8, "lo": 7, "hi": 8},
{"task": "T5", "quantity": "so_attack, N=300, sigma=2 (masking costs traces)", "expected": 0, "lo": 0, "hi": 3},
- {"task": "T5", "quantity": "so_attack, N=3000, sigma=2", "expected": 7.5, "lo": 6, "hi": 8},
+ {"task": "T5", "quantity": "so_attack, N=3000, sigma=2", "expected": 7.5, "lo": 4, "hi": 8},
{"task": "T6", "quantity": "max |t|, order 1, masks off, N=10000", "expected": 100, "lo": 20, "hi": 400},
{"task": "T6", "quantity": "max |t|, order 1, masks on, N=10000", "expected": 1.8, "lo": 0, "hi": 4.5},
{"task": "T6", "quantity": "max |t|, order 2, masks on, N=10000", "expected": 23, "lo": 8, "hi": 60},
diff --git a/labs/lab4_masking/handout.md b/labs/lab4_masking/handout.md
index 6d6f708..426ed7a 100644
--- a/labs/lab4_masking/handout.md
+++ b/labs/lab4_masking/handout.md
@@ -13,7 +13,7 @@ T1 `share`. T2 `fo_attack` (all share samples, best peak) - works unmasked and w
| unmasked, N=300, sigma=2: bytes of k1 right (of 8) | 8 | 8 |
| first-order on masked, N=10000, sigma=1 (chance 0.03) | 0 | 0-2 |
| second-order on masked, N=10000, sigma=2 | 8 | 7-8 |
-| second-order, N=300 / N=3000, sigma=2 | 0 / 7 | 0-3 / 6-8 |
+| second-order, N=300 / N=3000, sigma=2 | 0 / 7 | 0-3 / 4-8 |
| max abs t: order 1 masks off / order 1 masks on / order 2 masks on | about 100-150 / 1.8 / 23-34 | 20-400 / <= 4.5 / 8-60 |
| recombination leak, first-order attack, N=2000, sigma=2 | 8 | 7-8 |
diff --git a/labs/lab5_fault_tmr/grader.py b/labs/lab5_fault_tmr/grader.py
index 62a1a96..3845111 100644
--- a/labs/lab5_fault_tmr/grader.py
+++ b/labs/lab5_fault_tmr/grader.py
@@ -16,9 +16,10 @@ def band(e, v, what):
def table(m):
- if id(m) not in _TABLE:
- _TABLE[id(m)] = m.fault_table(300, seed(7))
- return _TABLE[id(m)]
+ # keep a reference to the module: a bare id() can be reused by the next graded module after GC
+ if id(m) not in _TABLE or _TABLE[id(m)][0] is not m:
+ _TABLE[id(m)] = (m, m.fault_table(300, seed(7)))
+ return _TABLE[id(m)][1]
def t1(m):
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..cfb7215
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,4 @@
+# The labs, graders and kit check need NumPy only.
+numpy>=1.24
+# Optional, for tests/test_explorer.py (it skips itself otherwise):
+# playwright>=1.44 then: python -m playwright install chromium
diff --git a/rtlseclab/tools/make_student_kit.py b/rtlseclab/tools/make_student_kit.py
new file mode 100644
index 0000000..0c3c072
--- /dev/null
+++ b/rtlseclab/tools/make_student_kit.py
@@ -0,0 +1,60 @@
+"""Export the student hand-out copy of the kit: everything a participant needs, without solution.py, answer_key.md,
+the facilitator guide, the kit self-tests or the generator tools.
+
+Usage: python -m rtlseclab.tools.make_student_kit [out_dir=dist/rtl-sec-lab-student]
+
+This keeps honest students from tripping over the answers; it is not an anti-cheating measure. The graders compare
+against reference models in rtlseclab/core/, so those models necessarily ship with the student copy (see README)."""
+import glob, os, shutil, sys
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+LAB_FILES = ("handout.md", "starter.py", "grader.py", "expected.json")
+PKG_SKIP = {"check.py", "tools", "__pycache__"}
+
+STUDENT_README = """# RTL-Sec-Lab - student copy
+
+Simulation only: every trace, fault, trojan and PUF in this kit comes from a simple assumed model, not from a device.
+
+Needs Python 3 and numpy. For each lab read `labs/labN_*/handout.md`, fill in the TODOs in `starter.py`, then grade yourself:
+
+ python labs/lab1_lfsr_break/grader.py labs/lab1_lfsr_break/starter.py
+
+The grader prints PASS or FAIL per task. `explorer/trace_explorer.html` (open it in a browser, works offline) goes with
+labs 3 and 4. `rtl/` holds the Verilog of the two hop engines for reading; the kit does not simulate RTL.
+"""
+
+
+def build(out):
+ if os.path.exists(out):
+ shutil.rmtree(out)
+ os.makedirs(out)
+ n = 0
+ for lab in sorted(glob.glob(os.path.join(ROOT, "labs", "lab*"))):
+ dst = os.path.join(out, "labs", os.path.basename(lab)); os.makedirs(dst)
+ for f in LAB_FILES:
+ shutil.copy2(os.path.join(lab, f), dst); n += 1
+ shutil.copytree(os.path.join(ROOT, "rtlseclab"), os.path.join(out, "rtlseclab"),
+ ignore=lambda d, names: [x for x in names if x in PKG_SKIP or x.endswith(".pyc")])
+ shutil.copytree(os.path.join(ROOT, "rtl"), os.path.join(out, "rtl"))
+ os.makedirs(os.path.join(out, "explorer"))
+ shutil.copy2(os.path.join(ROOT, "explorer", "trace_explorer.html"), os.path.join(out, "explorer"))
+ with open(os.path.join(out, "README.md"), "w") as f:
+ f.write(STUDENT_README)
+ leaked = [p for p in glob.glob(os.path.join(out, "**", "*"), recursive=True)
+ if os.path.basename(p) in ("solution.py", "answer_key.md", "facilitator_guide.md")]
+ assert not leaked, leaked
+ return n
+
+
+def main(argv=None):
+ argv = sys.argv[1:] if argv is None else argv
+ out = os.path.abspath(argv[0]) if argv else os.path.join(ROOT, "dist", "rtl-sec-lab-student")
+ if out == ROOT or ROOT.startswith(out + os.sep):
+ sys.exit("refusing to export over the kit itself: " + out)
+ n = build(out)
+ print("student kit: %d lab files + rtlseclab/ + rtl/ + explorer -> %s" % (n, out))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/robustness_result.txt b/tests/robustness_result.txt
index 723547b..7d99451 100644
--- a/tests/robustness_result.txt
+++ b/tests/robustness_result.txt
@@ -5,7 +5,7 @@ shift 3: all PASS
shift 4: all PASS
shift 5: all PASS
shift 6: all PASS
-shift 7: FAILS: FAIL T5 masking costs traces [assertion: second order, N=3000 = 5.00, expected within [6, 8]] (0.8s)
+shift 7: all PASS
shift 8: all PASS
shift 9: all PASS
shift 10: all PASS
@@ -18,4 +18,4 @@ shift 16: all PASS
shift 17: all PASS
shift 18: all PASS
shift 19: all PASS
-ROBUSTNESS: 19/20 shifts all-PASS
+ROBUSTNESS: 20/20 shifts all-PASS