# Security Operations Guide
> For Users and Operators: Deploying, configuring, and managing secure Peat meshes
## Concepts
### What is a Mesh?
A **mesh** is a group of Peat devices that communicate with each other over Bluetooth Low Energy. Each mesh is identified by:
- **mesh_id**: A short identifier (e.g., "DEMO", "ALPHA", "OPS1")
- **shared secret**: Optional 32-byte key for encryption
Devices only communicate with others in the same mesh.
### Security Levels
| **None** | No secret | None | Development, demos |
| **Mesh-Wide** | Shared secret | External eavesdroppers | Semi-trusted operations |
| **Per-Peer E2EE** | + E2EE enabled | + Other mesh members | Sensitive point-to-point |
## Creating a Mesh
### Step 1: Choose a Mesh ID
The mesh_id appears in BLE advertisements and filters which devices can join.
**Guidelines:**
- 4 characters recommended (fits in BLE advertisement)
- Alphanumeric only
- Unique per deployment/exercise
- **Not secret** - visible to anyone scanning BLE
```
Good: DEMO, OPS1, ALFA, TM42
Bad: SECRET-MESH (visible anyway)
Bad: test (too generic, conflicts likely)
```
### Step 2: Generate a Shared Secret (Recommended)
The shared secret provides encryption. All mesh members must have the same secret.
**Generating a secret:**
```bash
# Linux/macOS - generate random 32 bytes
openssl rand -hex 32
# Output example:
# a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
```
**Store the secret securely:**
- Password manager
- Secure notes app
- Encrypted file
- **Never** in plain text files or emails
### Step 3: Distribute the Secret
**Secure distribution methods:**
- QR code scan (in-person)
- Encrypted messaging app
- Secure file transfer
- Physical USB drive
**Insecure methods (avoid):**
- Unencrypted email
- SMS/text message
- Shared documents
- Verbal over radio
### Step 4: Configure Each Device
Each device needs:
1. Unique node_id (usually auto-generated from MAC)
2. Callsign (human-readable name)
3. mesh_id (same for all devices in mesh)
4. Shared secret (same for all devices, if using encryption)
**Example configuration:**
| Leader phone | 0x11111111 | ALPHA-1 | OPS1 | a1b2c3... |
| Team member 1 | 0x22222222 | ALPHA-2 | OPS1 | a1b2c3... |
| Team member 2 | 0x33333333 | ALPHA-3 | OPS1 | a1b2c3... |
| Sensor node | 0x44444444 | SENSOR-1 | OPS1 | a1b2c3... |
## Operating a Secure Mesh
### Verifying Encryption
After configuration, verify encryption is working:
1. **Check device status** - should show "Encryption: Enabled"
2. **Monitor BLE traffic** - encrypted packets start with `0xAE`
3. **Test with wrong key** - device with wrong secret cannot decode messages
### Monitoring Mesh Health
| Connected peers | Expected count | Missing devices |
| Sync frequency | Regular intervals | Long gaps |
| Decryption failures | 0 | Any failures (key mismatch?) |
| Peer timeouts | Occasional | Frequent (BLE interference?) |
### Handling Alerts
**Emergency Event Received:**
- Acknowledge via ACK response
- Verify source callsign
- Follow operational procedures
**Decryption Failed:**
- Verify sender is using correct mesh_id
- Verify sender has correct shared secret
- Check for data corruption (retry)
**Peer Lost:**
- Device moved out of BLE range
- Device powered off or battery dead
- BLE interference
## Membership Management
### Current Limitation
**Important:** peat-btle does not currently support:
- Removing specific devices from a mesh
- Blocking compromised devices
- Key rotation
If a device is compromised:
1. Generate new shared secret
2. Distribute to all **other** devices
3. Reconfigure all devices with new secret
4. Compromised device is now excluded
### Adding a New Device
1. Configure device with mesh_id and secret
2. Power on within BLE range of mesh
3. Device auto-discovers and joins
4. Verify device appears in peer list
### Removing a Device (Planned)
Currently requires changing the secret for all remaining devices. Future versions will support explicit revocation.
## Troubleshooting
### Device Not Joining Mesh
**Check:**
1. mesh_id matches exactly (case-sensitive)
2. Shared secret is identical (all 32 bytes)
3. BLE is enabled and functioning
4. Device is within BLE range (~100m line-of-sight)
**Common mistakes:**
- Typo in mesh_id
- Partial secret copy (need all 64 hex characters)
- BLE turned off
- Battery too low for BLE operation
### Cannot Decrypt Messages
**Symptoms:**
- Documents received but show as encrypted
- Decryption error in logs
- No sync data appearing
**Causes:**
1. **Wrong secret** - verify byte-for-byte match
2. **Wrong mesh_id** - key is derived from mesh_id + secret
3. **Encryption not enabled** - sender isn't encrypting
4. **Data corruption** - BLE transmission error
### Messages Not Reaching All Devices
**Check:**
1. All devices have encryption enabled (or all disabled)
2. Mixed encrypted/unencrypted doesn't work well
3. BLE range and line-of-sight
4. Peer timeout settings (default 45s)
### Per-Peer E2EE Not Working
**Symptoms:**
- Key exchange messages sent but session not established
- E2EE messages not decrypting
**Causes:**
1. E2EE not enabled on one or both sides
2. Max sessions limit reached (default 16)
3. Session timed out (default 30 minutes)
4. Key exchange messages not delivered
## Security Checklist
### Pre-Deployment
- [ ] Generated unique mesh_id for this operation
- [ ] Generated cryptographically secure 32-byte secret
- [ ] Distributed secret through secure channel
- [ ] Configured all devices with identical secret
- [ ] Verified encryption enabled on all devices
- [ ] Tested communication between all device pairs
- [ ] Documented device node_ids and callsigns
### During Operation
- [ ] Monitor peer count matches expected
- [ ] Watch for decryption errors (key mismatch)
- [ ] Note any devices dropping repeatedly
- [ ] Keep spare configured devices ready
### Post-Operation
- [ ] Change shared secret if devices were at risk
- [ ] Review any security alerts
- [ ] Update documentation with lessons learned
- [ ] Securely delete old secrets
## Reference
### Configuration Parameters
| mesh_id | "DEMO" | Network identifier |
| encryption_secret | None | 32-byte shared key |
| strict_encryption | false | Reject unencrypted when encryption enabled |
| peer_timeout_ms | 45000 | Remove stale peers after 45s |
| max_peers | 8 | Maximum tracked peers |
| sync_interval_ms | 5000 | Broadcast every 5s |
| e2ee_session_timeout | 1800000 | E2EE session expires after 30m |
### Strict Encryption Mode
Enable strict mode to reject unencrypted documents (prevents downgrade attacks):
```
with_encryption(secret) # Enable encryption
with_strict_encryption() # Also reject unencrypted
```
**Recommended deployment path:**
1. Deploy with encryption enabled, strict=false
2. Verify all nodes are encrypting (monitor logs)
3. Enable strict mode once all nodes confirmed
4. Monitor SecurityViolation events for attacks
### Power Profiles
| Aggressive | 20% | ~6 hours | High-activity, fast sync |
| Balanced | 10% | ~12 hours | Normal operations |
| LowPower | 2% | ~20 hours | Extended operations |
| UltraLow | 0.5% | ~36 hours | Minimal activity |
*Estimated for 300mAh smartwatch battery
### BLE Range
| LE 1M | ~100m | Baseline |
| LE 2M | ~50m | Lower (faster) |
| LE Coded S=2 | ~200m | Higher |
| LE Coded S=8 | ~400m | Highest |
### Document Size Limits
| BLE MTU | ~244 bytes typical |
| Encryption overhead | 30 bytes |
| E2EE overhead | 46 bytes |
| **Available payload** | **~170 bytes** |
## Glossary
| **mesh_id** | Identifier that groups devices into a network |
| **node_id** | Unique 32-bit identifier for each device |
| **callsign** | Human-readable name (e.g., "ALPHA-1") |
| **shared secret** | 32-byte key for mesh encryption |
| **E2EE** | End-to-end encryption between two specific peers |
| **CRDT** | Conflict-free data type that merges without conflicts |
| **peer** | Another device in the mesh |
| **stale** | A peer not seen within timeout period |
## Getting Help
- **Technical issues**: Check logs for error messages
- **Configuration help**: Review this guide and examples
- **Bug reports**: https://github.com/r-evolve/peat-btle/issues
- **Security concerns**: Contact security@defenseunicorns.com