docs/PROTOCOL_GUIDE.md

# iOS Protocol Guide

## Overview

This document describes the iOS protocols used by iOSDiag for device communication and diagnostics.

## USBMUX Protocol

### Purpose
Direct USB communication with iOS devices via the usbmuxd daemon.

### Connection Flow
1. Connect to usbmuxd socket (typically `/var/run/usbmuxd`)
2. Send HELLO message
3. Receive HELLO response
4. Send LISTEN message to monitor device events
5. Receive DEVICE_ATTACHED/DETACHED messages
6. Send CONNECT message to establish device connection
7. Receive RESULT message with status

### Message Format
```
Header (16 bytes):
  - Length (4 bytes, little-endian)
  - Version (4 bytes, little-endian)
  - Message Type (4 bytes, little-endian)
  - Tag (4 bytes, little-endian)

Payload:
  - Variable length based on message type
```

### Message Types
- `HELLO` (1): Initial handshake
- `DEVICE_ATTACHED` (2): Device connected
- `DEVICE_DETACHED` (3): Device disconnected
- `RESULT` (4): Operation result
- `LISTEN` (5): Listen for device events
- `CONNECT` (6): Connect to device
- `LISTEN_PAIR` (7): Listen for pairing events
- `PAIR_RECORD` (8): Pairing record

## Lockdown Protocol

### Purpose
Device configuration, service management, and pairing.

### Connection Flow
1. Establish USBMUX connection to port 62078
2. Send StartSession request
3. Receive StartSession response with session ID
4. Send service requests (GetValue, SetValue, StartService, etc.)
5. Receive responses

### Message Format
Plist-based messages over SSL/TLS:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Request</key>
    <string>GetValue</string>
    <key>Domain</key>
    <string>com.apple.mobile.battery</string>
    <key>Key</key>
    <string>BatteryCurrentCapacity</string>
  </dict>
</plist>
```

### Common Requests
- `GetValue`: Retrieve device property
- `SetValue`: Set device property
- `StartService`: Start a service
- `StartSession`: Begin session
- `StopSession`: End session
- `Pair`: Establish pairing
- `ValidatePair`: Verify pairing

### Common Domains
- `com.apple.mobile.battery`: Battery information
- `com.apple.mobile.device_name`: Device name
- `com.apple.mobile.firmware`: Firmware version
- `com.apple.mobile.hardware`: Hardware information
- `com.apple.mobile.system_services`: System services

## DiagnosticsRelay Protocol

### Purpose
Access hardware diagnostics and system information.

### Connection Flow
1. Establish Lockdown connection
2. Request DiagnosticsRelay service
3. Send diagnostic requests
4. Receive diagnostic responses

### Message Format
Plist-based messages:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Request</key>
    <string>Query</string>
    <key>Diagnostics</key>
    <array>
      <string>com.apple.mobile.battery</string>
      <string>com.apple.mobile.thermal</string>
    </array>
  </dict>
</plist>
```

### Common Diagnostics
- `com.apple.mobile.battery`: Battery metrics
- `com.apple.mobile.thermal`: Thermal information
- `com.apple.mobile.nand`: Storage health
- `com.apple.mobile.wifi`: Wi-Fi diagnostics
- `com.apple.mobile.power`: Power information

## CrashReport Protocol

### Purpose
Retrieve crash logs and panic information.

### Connection Flow
1. Establish Lockdown connection
2. Request CrashReportCopy service
3. Send file list request
4. Receive file list
5. Request individual files
6. Receive file contents

### File Locations
- `/var/mobile/Library/Logs/CrashReporter/`: Crash logs
- `/var/mobile/Library/Logs/panic.log`: Panic logs
- `/var/mobile/Library/Logs/system.log`: System logs

## Syslog Protocol

### Purpose
Stream system logs in real-time.

### Connection Flow
1. Establish Lockdown connection
2. Request Syslog service
3. Receive log messages as they occur
4. Parse and process messages

### Message Format
Text-based log entries:
```
<timestamp> <hostname> <process>[<pid>]: <message>
```

## CoreDevice Protocol

### Purpose
Network-based communication for newer iOS versions.

### Connection Flow
1. Establish network connection to device
2. Send CoreDevice handshake
3. Establish secure tunnel
4. Send requests through tunnel
5. Receive responses

### Advantages
- Network-based (no USB required)
- Supports multiple simultaneous connections
- Lower latency for repeated operations

## Pairing Process

### Overview
Devices must be paired before accessing sensitive services.

### Pairing Flow
1. User accepts pairing prompt on device
2. Device generates certificate
3. Host generates certificate
4. Certificates are exchanged
5. Pair record is stored locally
6. Future connections use stored pair record

### Pair Record Format
```json
{
  "DeviceCertificate": "base64-encoded-certificate",
  "HostCertificate": "base64-encoded-certificate",
  "HostPrivateKey": "base64-encoded-private-key",
  "HostID": "unique-host-identifier",
  "RootPrivateKey": "base64-encoded-root-key",
  "RootCertificate": "base64-encoded-root-certificate",
  "SystemBUID": "device-unique-identifier"
}
```

## Error Handling

### Common Errors
- `InvalidRequest`: Malformed request
- `InvalidResponse`: Unexpected response format
- `ServiceNotAvailable`: Service not running
- `InvalidService`: Service doesn't exist
- `PermissionDenied`: Insufficient permissions
- `DeviceNotFound`: Device disconnected
- `PairingRequired`: Device not paired

### Retry Strategy
- Exponential backoff: 100ms, 200ms, 400ms, 800ms, 1600ms
- Maximum retries: 5
- Timeout: 30 seconds per request

## Security Considerations

### SSL/TLS
- Lockdown uses SSL/TLS for encryption
- Certificate pinning for device verification
- Mutual authentication

### Cryptography
- RSA-2048 for key exchange
- AES-128-CBC for encryption
- SHA-256 for hashing

### Authentication
- Pairing-based authentication
- Session tokens
- Request signing

## Performance Optimization

### Connection Pooling
- Reuse connections when possible
- Lazy connection establishment
- Connection timeout management

### Pipelining
- Send multiple requests without waiting for responses
- Batch operations
- Parallel service access

### Caching
- Cache device properties
- Cache service availability
- Cache pair records

---

**Last Updated**: 2026-02-10  
**Version**: 1.0.0