mirror of
https://github.com/XieyangSun/TEMPEST-LoRa.git
synced 2025-12-23 16:50:18 +00:00
Update README.md
This commit is contained in:
XieyangSun
244
README.md
244
README.md
@@ -22,7 +22,6 @@
|
||||
|
||||
This repository contains the source code and instructions for reproducing the results of **"TEMPEST-LoRa: Cross-Technology Covert Communication"**, accepted to **ACM CCS 2025**.
|
||||
|
||||
---
|
||||
|
||||
## πΊ Demo Video
|
||||
|
||||
@@ -31,25 +30,6 @@ Watch our demonstration of TEMPEST-LoRa in action:
|
||||
[](https://www.bilibili.com/video/BV1PLKiz6Eao)
|
||||
[](https://www.youtube.com/watch?v=HDbdAZd6cLw)
|
||||
|
||||
|
||||
## π Table of Contents
|
||||
|
||||
- [Overview](#-overview)
|
||||
- [Media Coverage](#-media-coverage)
|
||||
- [Key Features](#-key-features)
|
||||
- [Hardware Requirements](#-hardware-requirements)
|
||||
- [Quick Start](#-quick-start)
|
||||
- [EMR Transmitter Setup](#-emr-transmitter-setup-matlab)
|
||||
- [LoRa Receiver Setup](#-lora-receiver-setup-cots-devices)
|
||||
- [Attack Samples](#-attack-samples)
|
||||
- [Important Notes](#-important-notes)
|
||||
- [Citation](#-citation)
|
||||
- [Errata](#-errata)
|
||||
- [Acknowledgments](#-acknowledgments)
|
||||
- [License](#-license)
|
||||
|
||||
---
|
||||
|
||||
## π¬ Overview
|
||||
|
||||
TEMPEST-LoRa demonstrates a novel cross-technology covert communication technique that exploits electromagnetic radiation (EMR) from video cables. By crafting malicious images or videos displayed on a monitor/projector/TV, we can cause the connected **VGA or HDMI cable** to emit electromagnetic radiation that encodes **LoRa-compatible packets**.
|
||||
@@ -68,8 +48,7 @@ TEMPEST-LoRa demonstrates a novel cross-technology covert communication techniqu
|
||||
---
|
||||
|
||||
## π° Media Coverage
|
||||
|
||||
Our research has been featured in several technology and security publications:
|
||||
The following articles provide excellent summaries our work:
|
||||
|
||||
- π [**Hackaday**](https://hackaday.com/2025/07/04/video-cable-becomes-transmitter-with-tempest-lora/) - "Video Cable Becomes Transmitter With TEMPEST-LoRa"
|
||||
- π [**RTL-SDR Blog**](https://www.rtl-sdr.com/tempest-lora-emitting-lora-packets-from-vga-or-hdmi-cables/) - "TEMPEST-LoRa: Emitting LoRa Packets from VGA or HDMI Cables"
|
||||
@@ -341,224 +320,3 @@ If you find this work useful in your research, please cite:
|
||||
## π License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
```
|
||||
|
||||
### 2. Set Payload Symbols
|
||||
|
||||
**File**: `GetLoRaPacketInfo.m`
|
||||
|
||||
Defines the symbol sequence representing the payload to be encoded as EMR.
|
||||
|
||||
**Default Payload** (SF=6): `"Hello, TEMPEST-LoRa"`
|
||||
|
||||
**Custom Payloads**:
|
||||
Sample physical-layer symbol encoding sequences (SF6-SF12) are provided in `/EMR Tx/PayloadSymbols`.
|
||||
|
||||
To use a custom payload:
|
||||
1. Load the desired symbol sequence from `/PayloadSymbols/`
|
||||
2. Replace `PacketInfo.Payload` in `GetLoRaPacketInfo.m` with the loaded `Index` variable
|
||||
|
||||
**Usage**:
|
||||
```matlab
|
||||
PacketInfo = GetLoRaPacketInfo;
|
||||
```
|
||||
|
||||
### 3. Generate Attack Video
|
||||
|
||||
**File**: `GenerateAttackVideo.m`
|
||||
|
||||
Generates an attack video file named `Attack-Video.avi` in the current directory. Individual frames are saved in `/EMR Tx/pics` (1.png, 2.png, ..., x.png).
|
||||
|
||||
**Usage**:
|
||||
```matlab
|
||||
GenerateAttackVideo(PacketInfo, Config);
|
||||
```
|
||||
|
||||
### Utility Scripts
|
||||
|
||||
#### `CalculateChirpPoints.p` and `CalculateSFD.p`
|
||||
|
||||
Calculate the pixel stream corresponding to each EMR chirp signal. These are used internally by `GenerateAttackVideo.m` to create the 1-D pixel stream, which is then reshaped into a 2-D attack image based on the configured resolution.
|
||||
|
||||
#### `BlackPic.m`
|
||||
|
||||
Generates black images for the first and last frames to mark video boundaries.
|
||||
|
||||
#### `ReverseLoRaPacket.m`
|
||||
|
||||
Analyzes chirps from captured physical-layer samples to extract encoded LoRa symbols (reverse-engineering aid).
|
||||
|
||||
**Workflow**:
|
||||
1. Use a COTS LoRa device (e.g., SX1262) to transmit data packets
|
||||
2. Capture physical-layer samples using USRP or SDR
|
||||
3. Analyze chirp encoding with `ReverseLoRaPacket.m`
|
||||
4. Manually save results to `/EMR Tx/PayloadSymbols`
|
||||
|
||||
#### `ShowSpectrum.m`
|
||||
|
||||
Visualizes the time-frequency graph of physical-layer signals (for debugging or calibration).
|
||||
|
||||
---
|
||||
|
||||
## π» LoRa Receiver Setup (COTS Devices)
|
||||
|
||||
### Option 1: SX1262 LoRa Node
|
||||
|
||||
#### Setup Steps
|
||||
|
||||
1. **Install Arduino IDE** on Windows 10/11
|
||||
2. **Install RadioLib** library ([Documentation](https://www.ardu-badge.com/RadioLib))
|
||||
3. **Connect SX1262 node** to computer via USB
|
||||
4. **Upload program**: Load `SX1262_Receive_Interrupt.ino` from RadioLib examples
|
||||
5. **Monitor reception**: Open Tools β Serial Monitor to view received packets (Data, RSSI, SNR)
|
||||
|
||||
#### Configuration Parameters
|
||||
|
||||
The default parameters in `SX1262_Receive_Interrupt.ino` are configured to decode the samples in the `AttackSamples` folder:
|
||||
|
||||
```cpp
|
||||
radio.setFrequency(915); // Center frequency (MHz)
|
||||
radio.setBandwidth(500); // LoRa bandwidth (kHz)
|
||||
radio.setSpreadingFactor(7); // Spreading factor (6-12)
|
||||
radio.setCodingRate(5); // Coding rate
|
||||
radio.setPreambleLength(4); // Preamble length
|
||||
```
|
||||
|
||||
**Reference**: For Lilygo SX1262 devices, see the [official tutorial](https://github.com/Xinyuan-LilyGO/LilyGo-LoRa-Series).
|
||||
|
||||
### Option 2: SX1302 LoRa Gateway
|
||||
|
||||
#### Hardware Setup
|
||||
|
||||
We tested with the [Waveshare SX1302 LoRaWAN Gateway HAT](https://www.waveshare.com/wiki/SX1302_LoRaWAN_Gateway_HAT) on Raspberry Pi.
|
||||
|
||||
#### Software Setup
|
||||
|
||||
1. **Configure SX1302_hal**: Follow the [SX1302_hal README](https://github.com/Lora-net/sx1302_hal)
|
||||
|
||||
2. **Reception Method 1** (Direct HAL):
|
||||
|
||||
Navigate to `/libloragw` folder and run:
|
||||
```bash
|
||||
./test_loragw_hal_rx -a 915 -b 915 -m 1250
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `-a`, `-b`: Center frequency (MHz)
|
||||
- `-m`: Chip model (1250, 1255, or 1257, depending on your gateway)
|
||||
|
||||
3. **Reception Method 2** (Packet Forwarder):
|
||||
|
||||
Navigate to `/packet_forwarder` folder and run:
|
||||
```bash
|
||||
./lora_pkt_fwd -c global_conf.json.sx1250.US915
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `-c`: Configuration file (modify `global_conf.json` for custom settings)
|
||||
|
||||
---
|
||||
|
||||
## π― Attack Samples
|
||||
|
||||
Pre-generated attack images and videos are provided in the `/AttackSamples` folder for quick reproduction.
|
||||
|
||||
### Naming Convention
|
||||
|
||||
Files are named according to their configuration:
|
||||
|
||||
```
|
||||
SF[SpreadFactor]_[Bandwidth]kHz_[Payload]_[CenterFreq]MHz_[FreqOffset]Offset.png
|
||||
```
|
||||
|
||||
**Example**: `SF6_500kHz_ABC_915MHz_+50kHzOffset.png`
|
||||
- Spread Factor: 6
|
||||
- Bandwidth: 500 kHz
|
||||
- Payload: "ABC"
|
||||
- Center Frequency: 915 MHz
|
||||
- Frequency Offset: +50 kHz
|
||||
|
||||
### Available Configurations
|
||||
|
||||
Multiple frequency offset versions are provided for each configuration to account for hardware variations.
|
||||
|
||||
---
|
||||
|
||||
## β οΈ Important Notes
|
||||
|
||||
### 1. Academic and Educational Use Only
|
||||
|
||||
> [!CAUTION]
|
||||
> This project is developed **solely for academic research and educational purposes**. It aims to explore cross-technology covert communication and reveal potential security risks. Please respect applicable laws, regulations, and ethical standards when working with side-channel signals or wireless technologies.
|
||||
|
||||
### 2. Display Settings
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Ensure display settings are **exactly 1080Γ1920 @ 60Hz**. Some monitors may show "60Hz" but actually run at 59.91Hz or 59.94Hz. Verify the **actual refresh rate** in your OS display settings:
|
||||
> - **Windows 10/11**: Settings β Display β Advanced Display Settings
|
||||
|
||||
### 3. Full-Screen Display
|
||||
|
||||
> [!NOTE]
|
||||
> Attack images/videos **must be displayed in full-screen mode**. Any media player (built-in or third-party like PotPlayer) can be used.
|
||||
|
||||
### 4. Frequency Calibration
|
||||
|
||||
> [!TIP]
|
||||
> In practice, the actual EMR frequency may deviate from the configured frequency by several kHz to hundreds of kHz.
|
||||
>
|
||||
> **Calibration Method**:
|
||||
> 1. Observe the frequency offset using USRP/SDR spectrum analyzer
|
||||
> 2. Modify `ConfigFile.LeakageOffset` in `CrossConfigFile.m` to compensate
|
||||
|
||||
### 5. Protected Code
|
||||
|
||||
> [!NOTE]
|
||||
> Some core MATLAB functions are provided in `.p` format to protect ongoing patent applications. Reviewers can run the code end-to-end as described in the instructions.
|
||||
|
||||
---
|
||||
|
||||
## π Citation
|
||||
|
||||
If you find this work useful in your research, please cite:
|
||||
|
||||
```bibtex
|
||||
@inproceedings{TEMPEST-LoRa,
|
||||
title={TEMPEST-LoRa: Cross-Technology Covert Communication},
|
||||
author={Xieyang Sun and Yuanqing Zheng and Wei Xi and Zuhao Chen and Zhizhen Chen and Han Hao and Zhiping Jiang and Sheng Zhong},
|
||||
booktitle={Proceedings of the ACM Conference on Computer and Communications Security (CCS)},
|
||||
year={2025}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## π Errata
|
||||
|
||||
We have identified the following typographical errors in the published paper (both arXiv and ACM versions):
|
||||
|
||||
> [!NOTE]
|
||||
> **Page 2, Introduction (Third Contribution)**
|
||||
> - **Error**: "21.6 bps"
|
||||
> - **Correction**: "21.6 kbps"
|
||||
> - The data rate should be in kilobits per second (kbps), not bits per second (bps).
|
||||
|
||||
> [!NOTE]
|
||||
> **Page 5, Figure 4 Caption**
|
||||
> - **Error**: "Hsync and Ysync"
|
||||
> - **Correction**: "Hsync and Vsync"
|
||||
> - The vertical synchronization signal should be referred to as Vsync, not Ysync.
|
||||
|
||||
We apologize for any confusion these errors may have caused.
|
||||
|
||||
---
|
||||
|
||||
## β€οΈ Acknowledgments
|
||||
|
||||
We thank the anonymous reviewers of ACM CCS and the research community for their valuable feedback and support. We are grateful for the collaborative efforts of all authors. We also acknowledge the pioneering research in wireless communications and side-channel analysis that has laid the foundation for this work.
|
||||
|
||||
---
|
||||
|
||||
## π License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
Reference in New Issue
Block a user