Skip to content

Commit c311eba

Browse files
LLJYLLJY
authored
Merge pull request #15 from LLJY/docs/lucas
Docs/lucas
2 parents 6a1f8d0 + 53d7c6e commit c311eba

3 files changed

Lines changed: 910 additions & 107 deletions

File tree

‎README.md‎

Lines changed: 42 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@
22

33
MASTR is a security-focused embedded system that establishes a secure communication channel between a host system and a hardware token (Raspberry Pi Pico W/Pico 2 W + ATECC608A). It utilizes a three-phase protocol to ensure mutual attestation, secure channel establishment, and runtime integrity verification.
44

5+
Navigate to [Quick Start Guide](#quick-start-guide) to get started.
6+
57
[![Protocol](https://img.shields.io/badge/Protocol-MASTR-blue)](docs/)
68
[![Firmware](https://img.shields.io/badge/Firmware-RP2040%2FRP2350-green)](src/)
7-
[![Host](https://img.shields.io/badge/Host-Python%203.8+-brightgreen)](host/)
9+
[![Host](https://img.shields.io/badge/Host-Python%203.13+-brightgreen)](host/)
810
[![Status](https://img.shields.io/badge/Status-Active-success)]()
911

1012
---
@@ -23,7 +25,6 @@ MASTR is a security-focused embedded system that establishes a secure communicat
2325
- [Software Requirements](#software-requirements)
2426
- [Quick Start Guide](#quick-start-guide)
2527
- [Building the Firmware](#building-the-firmware)
26-
- [Build for Raspberry Pi Pico W](#build-for-raspberry-pi-pico-w)
2728
- [Build for Raspberry Pi Pico 2 W (RP2350)](#build-for-raspberry-pi-pico-2-w-rp2350)
2829
- [Flashing the Firmware](#flashing-the-firmware)
2930
- [Build Options](#build-options)
@@ -47,8 +48,6 @@ MASTR is a security-focused embedded system that establishes a secure communicat
4748
- [Protocol Errors](#protocol-errors)
4849
- [TPM2 Issues](#tpm2-issues)
4950
- [Project Structure](#project-structure)
50-
- [Additional Resources](#additional-resources)
51-
- [Contributing](#contributing)
5251
- [License](#license)
5352

5453
---
@@ -115,10 +114,10 @@ Before you begin, ensure you have the following installed and configured:
115114

116115
#### Hardware Requirements
117116

118-
- **Raspberry Pi Pico W** or **Raspberry Pi Pico 2 W** (with WiFi)
119-
- **ATECC608A** secure element (connected via I2C at address 0x6A)
117+
- **Raspberry Pi Pico 2 W** (with WiFi)
118+
- **ATECC608A/B/C** secure element (connected via I2C at address 0x35) i2c address is configurable
120119
- **USB cable** for programming and serial communication
121-
- **Host computer** (Linux, macOS, or Windows)
120+
- **Host computer** (Linux, macOS, or POSIX Compliant OS ONLY)
122121

123122
#### Software Requirements
124123

@@ -173,11 +172,6 @@ git submodule update --init
173172
export PICO_SDK_PATH=$(pwd)
174173
```
175174

176-
**Windows:**
177-
- Install ARM GCC from [ARM Downloads](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads)
178-
- Install CMake from [cmake.org](https://cmake.org/download/)
179-
- Clone Pico SDK and set `PICO_SDK_PATH` environment variable
180-
181175
---
182176

183177
## Quick Start Guide
@@ -187,38 +181,41 @@ Follow these steps to get MASTR up and running from zero to a fully provisioned,
187181
### Step 1: Clone the Repository
188182

189183
```bash
190-
git clone <repository-url>
184+
git clone https://github.com/LLJY/MASTR
191185
cd MASTR-NEW
192186
```
193187

194188
### Step 2: Build the Firmware
195189

196190
```bash
197-
# For Raspberry Pi Pico W
191+
# For Raspberry Pi Pico 2W
198192
mkdir build
199193
cd build
200-
cmake .. -DPICO_BOARD=pico_w
201-
make
202-
cd ..
194+
# compiling in debug mode recommended for testing
195+
cmake .. -DPICO_BOARD=pico2_w -DENABLE_DEBUG=ON
196+
make -j$(nproc)
203197
```
204198

205-
### Step 3: Flash the Firmware
199+
### Step 3: Flash the Firmware (Picotool recommended)
206200

207-
1. Hold down the **BOOTSEL** button on your Pico W
208-
2. Connect the Pico W to your computer via USB
209-
3. The Pico W will appear as a mass storage device (RPI-RP2)
210-
4. Copy the firmware file to the device:
201+
Run the following command in the `build` folder:
211202
```bash
212-
cp build/mastr.uf2 /media/$USER/RPI-RP2/
203+
picotool load -f pico_project_template.uf2
213204
```
214-
(On Windows: drag and drop to the RPI-RP2 drive)
215-
5. The Pico W will automatically reboot and start running MASTR
205+
206+
The Pico W will automatically reboot and start running MASTR
216207

217208
### Step 4: Install Host Dependencies
218209

219210
```bash
220211
cd host/
221212
pip install -r requirements.txt
213+
214+
# pytss may fail to install due to wheel building, please get your distrubution specific version.
215+
# Ubuntu
216+
sudo apt-get install python3-tpm2-pytss
217+
218+
# you will also require build-essentials, tpm2-tools
222219
```
223220

224221
### Step 5: Provision the System
@@ -238,71 +235,49 @@ You should see successful authentication and a secure channel established!
238235

239236
## Building the Firmware
240237

241-
The firmware runs on Raspberry Pi Pico/Pico W with FreeRTOS and uses CMake for building.
242-
243-
### Build for Raspberry Pi Pico W
244-
245-
```bash
246-
# From project root
247-
mkdir build
248-
cd build
249-
250-
# Configure for Pico W (RP2040 with WiFi)
251-
cmake .. -DPICO_BOARD=pico_w
252-
253-
# Build
254-
make
255-
256-
# The output file will be: build/mastr.uf2
257-
```
238+
The firmware currently only runs on the Pico 2W, the standard Pico W is supported, but not tested.
258239

259-
### Build for Raspberry Pi Pico 2 W (RP2350)
240+
### Build for Raspberry Pi Pico 2W
260241

261242
```bash
262243
# From project root
263244
mkdir build
264245
cd build
265246

266-
# Configure for RP2350 platform
267-
cmake .. -DPICO_PLATFORM=rp2350 -DPICO_BOARD=pico2_w
247+
# Configure for Pico 2W (RP2350 with WiFi)
248+
cmake .. -DPICO_BOARD=pico2_w -DENABLE_DEBUG=ON
268249

269250
# Build
270-
make
251+
make -j$(nproc)
271252

272-
# The output file will be: build/mastr.uf2
253+
# The output file will be: build/pico_project_template.uf2
273254
```
274255

275256
### Flashing the Firmware
276257

277-
**BOOTSEL Method (Recommended):**
278-
279-
1. **Hold BOOTSEL button** while connecting USB cable
280-
2. Pico appears as mass storage device named **RPI-RP2**
281-
3. **Copy UF2 file** to the drive:
258+
**Using Picotool Method (Recommended):**
259+
1. After compilation, run the following command:
282260
```bash
283261
# Linux/macOS
284-
cp build/mastr.uf2 /media/$USER/RPI-RP2/
285-
286-
# Windows (replace D: with your drive letter)
287-
copy build\mastr.uf2 D:\
262+
picotool load -f pico_project_template.uf2
288263
```
289264
4. Device will **automatically reboot** and run the firmware
290265

291266
**Verify Firmware is Running:**
292-
- The token's WiFi AP should appear (check for SSID in your WiFi list)
267+
- The token's WiFi AP should appear as `MASTR-TOKEN` (check for SSID in your WiFi list)
293268
- Serial output should be visible on `/dev/ttyACM0` at 115200 baud
294269

295270
### Build Options
296271

297272
**Debug Build:**
298273
```bash
299-
cmake .. -DPICO_BOARD=pico_w -DCMAKE_BUILD_TYPE=Debug
274+
cmake .. -DPICO_BOARD=pico2_w -DCMAKE_BUILD_TYPE=Debug
300275
make
301276
```
302277

303278
**Release Build (Optimized):**
304279
```bash
305-
cmake .. -DPICO_BOARD=pico_w -DCMAKE_BUILD_TYPE=Release
280+
cmake .. -DPICO_BOARD=pico2_w -DCMAKE_BUILD_TYPE=Release
306281
make
307282
```
308283

@@ -313,7 +288,7 @@ cd ..
313288
rm -rf build
314289
mkdir build
315290
cd build
316-
cmake .. -DPICO_BOARD=pico_w
291+
cmake .. -DPICO_BOARD=pico2_w
317292
make
318293
```
319294

@@ -1264,12 +1239,12 @@ MASTR-NEW/
12641239

12651240
## Additional Resources
12661241

1267-
- **[PROVISIONING.md](/home/lucas/Projects/Embed/MASTR-NEW/PROVISIONING.md)** - Detailed provisioning guide
1268-
- **[QUICK_START_TPM2.md](/home/lucas/Projects/Embed/MASTR-NEW/QUICK_START_TPM2.md)** - TPM2 setup and usage
1269-
- **[host/README.md](/home/lucas/Projects/Embed/MASTR-NEW/host/README.md)** - Python host implementation details
1270-
- **[host/ARCHITECTURE.md](/home/lucas/Projects/Embed/MASTR-NEW/host/ARCHITECTURE.md)** - Detailed architecture documentation
1271-
- **[docs/provisioning_flow.md](/home/lucas/Projects/Embed/MASTR-NEW/docs/provisioning_flow.md)** - Provisioning flow diagrams
1272-
- **[docs/ap_http_architecture.md](/home/lucas/Projects/Embed/MASTR-NEW/docs/ap_http_architecture.md)** - WiFi AP and HTTP architecture
1242+
- **[PROVISIONING.md](./PROVISIONING.md)** - Detailed provisioning guide
1243+
- **[QUICK_START_TPM2.md](./QUICK_START_TPM2.md)** - TPM2 setup and usage
1244+
- **[host/README.md](./host/README.md)** - Python host implementation details
1245+
- **[host/ARCHITECTURE.md](./host/ARCHITECTURE.md)** - Detailed architecture documentation
1246+
- **[docs/provisioning_flow.md](./docs/provisioning_flow.md)** - Provisioning flow diagrams
1247+
- **[docs/ap_http_architecture.md](./docs/ap_http_architecture.md)** - WiFi AP and HTTP architecture
12731248

12741249
**External Resources:**
12751250
- [Raspberry Pi Pico SDK Documentation](https://raspberrypi.github.io/pico-sdk-doxygen/)
@@ -1302,53 +1277,13 @@ Contributions are welcome! Please follow these guidelines:
13021277
8. **Push to the branch** (`git push origin feature/amazing-feature`)
13031278
9. **Open a Pull Request**
13041279

1305-
**Code Review Criteria:**
1306-
- Functionality correctness
1307-
- Security implications
1308-
- Code style compliance
1309-
- Test coverage
1310-
- Documentation updates
1311-
13121280
---
13131281

13141282
## License
13151283

1316-
This project is licensed under the terms specified in [LICENSE.TXT](/home/lucas/Projects/Embed/MASTR-NEW/LICENSE.TXT).
1317-
1318-
---
1319-
1320-
## Security Considerations
1321-
1322-
**Production Deployment Checklist:**
1323-
1324-
- [ ] Use TPM2Crypto backend (not NaiveCrypto)
1325-
- [ ] Verify ATECC608A is properly configured
1326-
- [ ] Use strong WiFi passwords (generated via `/api/claim`)
1327-
- [ ] Update golden hash to match production firmware
1328-
- [ ] Disable debug message types in production firmware
1329-
- [ ] Use HTML UI for provisioning (not debug serial protocol)
1330-
- [ ] Secure physical access to token
1331-
- [ ] Implement proper key rotation policies
1332-
- [ ] Monitor for integrity verification failures
1333-
- [ ] Log all authentication attempts
1334-
1335-
**Known Limitations:**
1336-
- Debug protocol messages should be disabled in production
1337-
- WiFi AP uses WPA2 (consider WPA3 when supported by hardware)
1338-
- Session keys are ephemeral but not rotated during runtime
1339-
- Heartbeat timeout values may need tuning for specific deployments
1284+
This project is licensed under the BSD 3-Clause License as specified in [LICENSE.TXT](./LICENSE.TXT).
13401285

13411286
---
1342-
1343-
## Acknowledgments
1344-
1345-
- Raspberry Pi Foundation for Pico SDK
1346-
- Microchip for ATECC608A and CryptoAuthLib
1347-
- FreeRTOS for RTOS kernel
1348-
- Unity Test Framework
1349-
1350-
---
1351-
13521287
**Last Updated:** 2025-11-23
13531288
**Version:** 3.0 (Production Ready with Full Provisioning Support)
13541289

0 commit comments

Comments
 (0)