diff --git a/README.md b/README.md index b371648..f9d55d8 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ A terminal-based RF signal analysis tool for capturing, decoding, and retransmit - **Real-time capture** — receive and demodulate AM/OOK keyfob signals at configurable frequencies (HackRF uses AM envelope detection; FM protocols are tagged for display and may decode when signal is strong) - **Multi-protocol decoding** — 14 protocol decoders: Kia V0–V6, Ford V0, Fiat V0, Subaru, Suzuki, VAG (VW/Audi/Seat/Skoda), PSA, Scher-Khan, Star Line; adaptive demodulation for real-world conditions +- **KeeLoq generic fallback** — when a signal doesn’t match any known protocol, KAT tries decoding it as KeeLoq using every manufacturer key in the embedded keystore (Kia V3/V4 and Star Line air formats); successful decodes appear as **Keeloq (keystore name)** in the capture list - **RF modulation metadata** — each protocol tagged as AM, FM, or both (from ProtoPirate); shown in signal detail and exported in .fob - **Rich signal detail** — encoding (PWM/Manchester), RF (AM/FM), encryption, serial, counter, key data, CRC, frequency, and raw level/duration pairs - **Signal retransmission** — transmit Lock, Unlock, Trunk, and Panic commands from decoded captures (VAG supports full encode from capture via stored vag_type/key_idx) @@ -215,9 +216,11 @@ Protocol behavior and RF modulation (AM/FM) follow the ProtoPirate reference. KA | Star Line | PWM | AM | KeeLoq | 433.92 MHz | | PSA (Peugeot/Citroën) | Manchester | FM | XTEA/XOR | 433.92 MHz | +**KeeLoq generic fallback:** If no protocol decodes a capture, KAT tries KeeLoq with every keystore manufacturer key (Kia V3/V4 and Star Line bit layouts). On success the protocol is shown as **Keeloq (*keystore name*)** (e.g. Keeloq (Alligator), Keeloq (Pandora_PRO)). See [docs/keeloq_generic.md](docs/keeloq_generic.md). + ### Cryptographic modules -- **KeeLoq** — encrypt/decrypt with normal, secure, FAAC, and magic serial/XOR learning key derivation (keeloq_common, keys) +- **KeeLoq** — encrypt/decrypt with normal, secure, FAAC, and magic serial/XOR learning key derivation (keeloq_common, keys). Unknown signals are tried as KeeLoq with every keystore key via **keeloq_generic** (uses keeloq_common only). - **AUT64** — 12-round block cipher for VAG type 1/3/4 (aut64) - **Keystore** — manufacturer keys (Kia, VAG, etc.) built in; see `src/keystore/` @@ -253,7 +256,8 @@ src/ ├── protocols/ │ ├── mod.rs # Protocol registry, decoder trait, duration_diff macro │ ├── common.rs # DecodedSignal (extra for VAG encode), CRC, bit helpers, button codes -│ ├── keeloq_common.rs # KeeLoq cipher + learning key algorithms +│ ├── keeloq_common.rs # KeeLoq cipher + learning key algorithms (used by Kia V3/V4, Star Line, keeloq_generic) +│ ├── keeloq_generic.rs # KeeLoq fallback: try every keystore key when no protocol matches (uses keeloq_common) │ ├── aut64.rs # AUT64 block cipher (VAG) │ ├── keys.rs # Key loading (embedded + optional file), KIA/VAG │ ├── kia_v0..kia_v6.rs diff --git a/docs/README.md b/docs/README.md index 951e662..637e826 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,5 +20,8 @@ This folder describes how each keyfob protocol supported by KAT works. Each docu | Scher-Khan | `scher_khan.rs` | [scher_khan.md](scher_khan.md) | | Star Line | `star_line.rs` | [star_line.md](star_line.md) | | PSA | `psa.rs` | [psa.md](psa.md) | +| KeeLoq generic (fallback) | `keeloq_generic.rs` | [keeloq_generic.md](keeloq_generic.md) | + +**KeeLoq generic** is not a registered decoder; it runs when no protocol matches and tries KeeLoq with every keystore manufacturer key (using `keeloq_common`). Successful decodes appear as **Keeloq (*keystore name*)**. Implementations are aligned with the ProtoPirate reference in `REFERENCES/ProtoPirate/protocols/`. diff --git a/docs/keeloq_generic.md b/docs/keeloq_generic.md new file mode 100644 index 0000000..b7d35b6 --- /dev/null +++ b/docs/keeloq_generic.md @@ -0,0 +1,42 @@ +# KeeLoq Generic Fallback + +**Rust module:** `src/protocols/keeloq_generic.rs` +**Helper:** `src/protocols/keeloq_common.rs` (decrypt, normal learning) + +## Overview + +When no known protocol decodes a captured signal, KAT tries to decode it as **KeeLoq** using every manufacturer key in the embedded keystore. All decryption is done via the **keeloq_common** helper (no protocol-specific decrypt code). Two air formats are supported: + +1. **Kia V3/V4 format** — 68 bits, 400/800 µs PWM, 315 or 433.92 MHz +2. **Star Line format** — 64 bits, 250/500 µs PWM, 433.92 MHz + +Bit collection reuses the existing Kia V3/V4 and Star Line state machines; decryption and validation use only **keeloq_common** (`keeloq_decrypt`, `keeloq_normal_learning`, `reverse_key`, `reverse8`). + +## When it runs + +- After all registered protocol decoders have been tried (both normal and inverted polarity). +- Only if the signal was not decoded as Kia V3/V4, Star Line, or any other protocol. + +## Display + +On first successful decrypt with a given key, the capture is shown in the list with: + +- **Protocol:** `Keeloq (keystore name)` — e.g. `Keeloq (Alligator)`, `Keeloq (Pandora_PRO)`, `Keeloq (KIA)`. +- Serial, button, counter, CRC, and data as for other KeeLoq decodes. + +## Keystore + +Uses **all** KeeLoq manufacturer keys from the embedded blob (types 0, 1, 2, 10, 20). Key names come from `keystore::KEY_ENTRY_NAMES` and are used only for the displayed protocol label. + +## Encoding + +Captures decoded as **Keeloq (*name*)** are decode-only in this path. Retransmit (Lock/Unlock/Trunk/Panic) is supported only for the named protocols **Kia V3/V4** and **Star Line**; to encode, the signal would need to have been decoded by those decoders (or you would need a separate encoder mapping for generic KeeLoq). + +## Flow + +1. Get `keeloq_mf_keys_with_names()` from the keystore. +2. If frequency is 315 or 433.92 MHz: for each polarity, run `collect_kia_v3_v4_bits`; for each key, run Kia V3/V4 byte layout + `keeloq_decrypt`; on validation match, return `("Keeloq (name)", decoded)`. +3. If frequency is 433.92 MHz: for each polarity, run `collect_star_line_bits`; for each key, try simple then normal learning with `keeloq_decrypt` / `keeloq_normal_learning`; on match, return `("Keeloq (name)", decoded)`. +4. If no key validates, return `None` (capture stays unknown or is shown as unknown in research mode). + +Implementations are aligned with the ProtoPirate reference; keeloq_common matches `REFERENCES/ProtoPirate/protocols/keeloq_common.c`.