Overview

Relevant source files

• Cargo.lock
• Cargo.toml
• README.md
• idevice/Cargo.toml
• idevice/src/lib.rs
• tools/Cargo.toml

This document provides a high-level introduction to the idevice library, explaining its purpose, architecture, and capabilities. The idevice library is a pure Rust implementation for communicating with iOS devices, supporting over 30 iOS services through a modular feature flag system.

For detailed information about specific subsystems:

• Project structure and workspace organization: see Project Structure
• Feature flag system and modularity: see Feature Flags and Modularity
• Core library architecture and abstractions: see Core Library Architecture
• Communication protocols: see Communication Protocols
• Specific device services: see Device Services
• FFI and language bindings: see FFI and Language Bindings
• Command-line tools: see Command Line Tools

Purpose and Motivation

The idevice library enables programmatic interaction with iOS devices using native code. It is designed to replace or complement existing iOS communication libraries like libimobiledevice, pymobiledevice3, and go-ios by providing a modern, embeddable solution written in pure Rust.

Sources: README.md1-41

Why Pure Rust?

The library addresses several limitations of existing solutions:

Library	Limitation	idevice Solution
libimobiledevice	Outdated, lacks modern iOS features	Active development with iOS 17+ support
pymobiledevice3	Requires Python interpreter	Native code, no runtime dependencies
go-ios	Difficult to embed in other languages	FFI support for C, C++, Swift

The library is currently deployed in production applications including StikDebug, CrossCode, and Protokolle, running on tens of thousands of devices worldwide.

Sources: README.md23-40

Workspace Architecture

The repository is organized as a Cargo workspace containing four primary components:

The workspace is defined in Cargo.toml1-10 with three member crates: ffi, idevice, and tools. Each component serves a distinct purpose in the overall architecture, from the core protocol implementations to high-level language bindings.

Sources: Cargo.toml1-10 README.md1-18 idevice/Cargo.toml1-12 tools/Cargo.toml1-11

Core Abstractions

The library is built on several key abstractions that provide a consistent interface for device communication:

Key Types

Type	Location	Purpose
ReadWrite	idevice/src/lib.rs53	Trait combining async I/O requirements
Idevice	idevice/src/lib.rs151-158	Main connection handle with socket management
IdeviceService	idevice/src/lib.rs62-121	Trait for legacy lockdown-based services
RsdService	idevice/src/lib.rs124-138	Trait for modern RSD-based services
IdeviceProvider	See Provider Abstraction	Factory for creating device connections
IdeviceError	idevice/src/lib.rs648-1032	Comprehensive error enum with 60+ variants

The Idevice struct idevice/src/lib.rs151-158 wraps a Box<dyn ReadWrite> socket, providing methods for plist serialization (idevice/src/lib.rs255-272), raw I/O (idevice/src/lib.rs306-416), and TLS session establishment (idevice/src/lib.rs554-644).

Sources: idevice/src/lib.rs46-158 idevice/src/lib.rs648-1032

Service Categories

The library implements over 30 iOS device services, organized into functional categories through Cargo feature flags:

Each service is gated behind a feature flag in idevice/Cargo.toml68-155 The lockdownd service is always enabled as it provides the foundation for discovering and connecting to other services.

Service Implementation Pattern

Services implement either IdeviceService for legacy services or RsdService for modern iOS 17+ services:

Legacy Service Pattern (implements IdeviceService):

1. Service name returned by service_name() idevice/src/lib.rs64
2. Connection via connect() using lockdown protocol idevice/src/lib.rs76-117
3. Stream initialization via from_stream() idevice/src/lib.rs120

Modern Service Pattern (implements RsdService):

1. Service name returned by rsd_service_name() idevice/src/lib.rs125
2. Connection via connect_rsd() using RSD protocol idevice/src/lib.rs129-137
3. Stream initialization via from_stream() idevice/src/lib.rs126-128

Sources: idevice/Cargo.toml68-155 README.md46-70 idevice/src/lib.rs62-138

Multi-Language Support

The library provides a three-tier architecture for cross-language interoperability:

Memory Management

The FFI layer follows a strict ownership protocol:

1. Allocation: Rust creates objects with Box::into_raw(), returning *mut T to C/C++
2. Ownership Transfer: C/C++ code receives and stores the pointer
3. Deallocation: C/C++ calls *_free() functions, which use Box::from_raw() to drop properly

Example pattern from FFI layer:

• Client creation returns opaque handle: *mut LockdownClientHandle
• Client operations accept handle: fn lockdown_get_value(client: *mut LockdownClientHandle, ...)
• Client cleanup: fn lockdown_client_free(client: *mut LockdownClientHandle)

C++ wrappers encapsulate this with RAII using std::unique_ptr with custom deleters, ensuring automatic cleanup when objects go out of scope.

Sources: README.md146-184 idevice/src/lib.rs1-1032

Connection Pathways

Device communication follows two distinct pathways depending on the iOS version and service type:

The IdeviceService::connect() method idevice/src/lib.rs76-117 implements the legacy pathway, while RsdService::connect_rsd() idevice/src/lib.rs129-137 implements the modern pathway. Both ultimately produce a service client ready for operations.

Sources: idevice/src/lib.rs62-138

Feature Flag System

To minimize binary size and compile times, the library uses an extensive feature flag system where each service and protocol component is optional:

Feature Category	Features	Dependencies
TLS Backends	rustls (default), openssl, aws-lc, ring	Mutually exclusive crypto providers
File Services	afc, house_arrest, crashreportcopymobile	chrono, futures
Device Management	diagnostics_relay, heartbeat, misagent	Minimal dependencies
Development	dvt, debug_proxy, screenshotr, pcapd	byteorder, ns-keyed-archive
Apps	installation_proxy, springboardservices	async_zip, futures
Modern iOS 17+	core_device, core_device_proxy, rsd, xpc	uuid, indexmap, async-stream
Network	tcp, usbmuxd, tunnel_tcp_stack	tokio/net, crossfire
System	tss, tunneld, mobilebackup2, pair	reqwest, sha2, rsa, x509-cert

The full feature idevice/Cargo.toml121-155 enables all available services. Individual features can be selected for minimal builds:

This modularity allows applications to compile only the code they need. For example, a simple file transfer tool might only enable afc, usbmuxd, and a TLS backend, while a comprehensive device management application would use the full feature.

Sources: idevice/Cargo.toml68-155 README.md42-89

Error Handling

The library uses a comprehensive error enum IdeviceError idevice/src/lib.rs648-1032 with over 60 error variants covering:

• Transport errors (Socket, TLS)
• Protocol errors (Plist parsing, unexpected responses)
• Device-reported errors (GetProhibited, InvalidHostID, SessionInactive)
• Service-specific errors (AfcError, InstallationProxyOperationFailed)
• FFI boundary errors (FfiInvalidArg, FfiBufferTooSmall)

The error type implements conversion from device error strings idevice/src/lib.rs879-913 mapping common error codes like "GetProhibited", "InvalidHostID", and "DeviceLocked" to typed enum variants. This enables proper error propagation from device responses through the Rust API.

Each error variant has an associated error code idevice/src/lib.rs915-1032 for FFI compatibility, allowing C/C++ code to handle errors numerically.

Sources: idevice/src/lib.rs648-1032