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.** + +[![CI](https://github.com/Kavin-Re/RTL-Sec-Lab/actions/workflows/ci.yml/badge.svg)](https://github.com/Kavin-Re/RTL-Sec-Lab/actions/workflows/ci.yml) +![Python + NumPy only](https://img.shields.io/badge/deps-python%20%2B%20numpy-blue) +![39 graded tasks](https://img.shields.io/badge/graded%20tasks-39-informational) +![Scope: simulation only](https://img.shields.io/badge/scope-simulation%20only-lightgrey) + +> **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. + +![Trace explorer, unmasked traces](tests/screens/01_unmasked.png) + +## 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