tunnel

Documentation

Overview

Package tunnel implements creating a TUN interface for iOS 17 devices. These tunnels are used to connect to services running on the device. On older iOS versions this was done over the 'usbmuxd'-socket. Services that are available via usbmuxd can also be used over the tunnel (they are listed in remote service discovery).

Starting a tunnel is a two-step process:

- Pair Device/Verify Device Pairing

- Setting up a TUN interface

Device Pairing

The step of device pairing means either that a new pairing is set up, or credentials from an already existing pairing are verified. For device pairing we connect to the RemoteXPC service 'com.apple.internal.dt.coredevice.untrusted.tunnelservice' directly on the ethernet interface exposed by the device. Process: - host -> device : 'setupManualPairing' request

- device -> host : device public key and salt to initialize SRP

- host -> device : host public key and SRP client proof

- device -> host : SRP host proof

- host -> device : host info (signed with the key from the host pair record) encrypted with the session key obtained through SRP

- device -> host : device info encrypted with the same key as above

Verifying a device pairing works by signing the host identifier (which is part of the pair record on the host) with a key derived through ECDH. The public keys used there are the key of the pair record on the host and the device provides a public key when the host asks to verify the pairing.

Tunnel Interface

For the TUN interface we continue to use the same connection that we opened for the device pairing. The host asks the device to create a listener, and provides a public key, as well as the requested tunnel type. There are two types of tunnels that can be created, QUIC and TCP. In this package only QUIC is supported. The device will respond with a public key and a port number on which the tunnel endpoint listens on the device. The host opens a QUIC connection using a self-signed certificate with the public key that was sent to the device earlier. The first messages on this QUIC connection exchange the parameters for this tunnel. The host sends a 'clientHandshakeRequest' containing the MTU used for the TUN interface, and the device responds with the information about what IP addresses the host and the device have to use for this tunnel, as well as the port on which remote service discovery (RSD) is reachable on the device

After that all services listed in RSD are available via this TUN interface

Index

• Constants
• func ServeTunnelInfo(tm *TunnelManager, port int) error
• type PairRecordManager
  • func NewPairRecordManager(p string) (PairRecordManager, error)
  • func (p PairRecordManager) StoreDeviceInfo(d device) error
• type Tunnel
  • func ConnectTunnelLockdown(device ios.DeviceEntry) (Tunnel, error)
  • func ListRunningTunnels(tunnelInfoPort int) ([]Tunnel, error)
  • func ManualPairAndConnectToTunnel(ctx context.Context, device ios.DeviceEntry, p PairRecordManager) (Tunnel, error)
  • func TunnelInfoForDevice(udid string, tunnelInfoPort int) (Tunnel, error)
  • func (t Tunnel) Close() error
• type TunnelManager
  • func NewTunnelManager(pm PairRecordManager) *TunnelManager
  • func (m *TunnelManager) FindTunnel(udid string) (Tunnel, error)
  • func (m *TunnelManager) ListTunnels() ([]Tunnel, error)
  • func (m *TunnelManager) UpdateTunnels(ctx context.Context) error

Constants

const DefaultHttpApiPort = 28100

DefaultHttpApiPort is the port on which we start the HTTP-Server for exposing started tunnels

Functions

func ServeTunnelInfo

func ServeTunnelInfo(tm *TunnelManager, port int) error

ServeTunnelInfo starts a simple http serve that exposes the tunnel information about the running tunnel. The API has two endpoints: 1. GET localhost:{PORT}/tunnel/{UDID} to get the tunnel info for a specific device 2. DELETE localhost:{PORT}/tunnel/{UDID} to stop a device tunnel 3. GET localhost:{PORT}/tunnels to get a list of all tunnels

Types

type PairRecordManager

type PairRecordManager struct {
	// contains filtered or unexported fields
}

PairRecordManager implements the same logic as macOS related to remote pair records. Those pair records are used whenever a tunnel gets created.

func NewPairRecordManager

func NewPairRecordManager(p string) (PairRecordManager, error)

NewPairRecordManager creates a PairRecordManager that reads/stores the pair records information at the given path To use the same pair records as macOS does, this path should be /var/db/lockdown/RemotePairing/user_501 (user_501 is the default for the root user)

func (PairRecordManager) StoreDeviceInfo

func (p PairRecordManager) StoreDeviceInfo(d device) error

StoreDeviceInfo stores the provided Device info as a plist encoded file in the `peers/` directory

type Tunnel

type Tunnel struct {
	// Address is the IPv6 address of the device over the tunnel
	Address string `json:"address"`
	// RsdPort is the port on which remote service discover is reachable
	RsdPort int `json:"rsdPort"`
	// Udid is the id of the device for this tunnel
	Udid string `json:"udid"`
	// contains filtered or unexported fields
}

Tunnel describes the parameters of an established tunnel to the device

func ConnectTunnelLockdown

func ConnectTunnelLockdown(device ios.DeviceEntry) (Tunnel, error)

func ListRunningTunnels

func ListRunningTunnels(tunnelInfoPort int) ([]Tunnel, error)

func ManualPairAndConnectToTunnel

func ManualPairAndConnectToTunnel(ctx context.Context, device ios.DeviceEntry, p PairRecordManager) (Tunnel, error)

ManualPairAndConnectToTunnel tries to verify an existing pairing, and if this fails it triggers a new manual pairing process. After a successful pairing a tunnel for this device gets started and the tunnel information is returned

func TunnelInfoForDevice

func TunnelInfoForDevice(udid string, tunnelInfoPort int) (Tunnel, error)

func (Tunnel) Close

func (t Tunnel) Close() error

Close closes the connection to the device and removes the virtual network interface from the host

type TunnelManager

type TunnelManager struct {
	// contains filtered or unexported fields
}

TunnelManager starts tunnels for devices when needed (if no tunnel is running yet) and stores the information how those tunnels are reachable (address and remote service discovery port)

func NewTunnelManager

func NewTunnelManager(pm PairRecordManager) *TunnelManager

NewTunnelManager creates a new TunnelManager instance for setting up device tunnels for all connected devices

func (*TunnelManager) FindTunnel

func (m *TunnelManager) FindTunnel(udid string) (Tunnel, error)

func (*TunnelManager) ListTunnels

func (m *TunnelManager) ListTunnels() ([]Tunnel, error)

ListTunnels provides all currently running device tunnels

func (*TunnelManager) UpdateTunnels

func (m *TunnelManager) UpdateTunnels(ctx context.Context) error

UpdateTunnels checks for connected devices and starts a new tunnel if needed On device disconnects the tunnel resources get cleaned up