Hugging Face's logo

meccatronis
/
iosdiag

Model card Files
xet
 Community
iosdiag / docs /PROTOCOL_GUIDE.md
meccatronis's picture
meccatronis
Upload docs/PROTOCOL_GUIDE.md with huggingface_hub
b4ec2f6 verified
preview code
|
Raw History Blame Contribute Delete
6.43 kB

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 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 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 

{
  "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