The iPhone Wiki is no longer updated. Visit this article on The Apple Wiki for current information.

Normal Mode

From The iPhone Wiki
Revision as of 01:35, 13 August 2008 by Codebar (talk | contribs) (→‎MobileDevice Header (mobiledevice.h))
Jump to: navigation, search

This is the protocol iTunes uses to talk to the booted iPhone. It uses usbmux to provide TCP like connectivity over a USB port using SSL. There is a pairing process iTunes uses to establish the secure channel.

MobileDevice Library

PC Windows : iTunesMobileDevice.dll

  • Location : C:\Program Files\Common Files\Apple\Mobile Device Support\bin\iTunesMobileDevice.dll
  • Export : itunesmobiledevice.dll

Mac OSX : MobileDevice.framework

  • Location : /System/Library/PrivateFrameworks/MobileDevice.framework
  • Export command : "nm /System/Library/PrivateFrameworks/MobileDevice.framework/Versions/A/MobileDevice"

MobileDevice Header (mobiledevice.h)

Reversed engineering : C header for MobileDevice Library.

/* ---------------------------------------------------------------------------- 

*   MobileDevice.h - interface to MobileDevice.framework 
* ------------------------------------------------------------------------- */
  1. pragma once
  1. ifndef MOBILEDEVICE_H
  2. define MOBILEDEVICE_H
  1. ifdef __cplusplus

extern "C" {

  1. endif
  1. ifndef __GCC__
  2. pragma pack
  3. define __PACK
  4. else
  5. define __PACK __attribute__((__packed__))
  6. endif
  1. if defined(WIN32)
  2. define __DLLIMPORT [DllImport("iTunesMobileDevice.dll")]

using namespace System::Runtime::InteropServices;

  1. include <CoreFoundation.h>

typedef unsigned int mach_error_t;

  1. elif defined(__APPLE__)
  2. define __DLLIMPORT
  3. include <CoreFoundation/CoreFoundation.h>
  4. include <mach/error.h>
  5. endif

/* Error codes */

  1. define MDERR_APPLE_MOBILE (err_system(0x3a))
  2. define MDERR_IPHONE (err_sub(0))

/* Apple Mobile (AM*) errors */

  1. define MDERR_OK ERR_SUCCESS
  2. define MDERR_SYSCALL (ERR_MOBILE_DEVICE | 0x01)
  3. define MDERR_OUT_OF_MEMORY (ERR_MOBILE_DEVICE | 0x03)
  4. define MDERR_QUERY_FAILED (ERR_MOBILE_DEVICE | 0x04)
  5. define MDERR_INVALID_ARGUMENT (ERR_MOBILE_DEVICE | 0x0b)
  6. define MDERR_DICT_NOT_LOADED (ERR_MOBILE_DEVICE | 0x25)

/* Apple File Connection (AFC*) errors */

  1. define MDERR_AFC_OUT_OF_MEMORY 0x03

/* USBMux errors */

  1. define MDERR_USBMUX_ARG_NULL 0x16
  2. define MDERR_USBMUX_FAILED 0xffffffff

/* Messages passed to device notification callbacks: passed as part of * am_device_notification_callback_info. */

  1. define ADNCI_MSG_CONNECTED 1
  2. define ADNCI_MSG_DISCONNECTED 2
  3. define ADNCI_MSG_UNKNOWN 3
  1. define AMD_IPHONE_PRODUCT_ID 0x1290

//#define AMD_IPHONE_SERIAL ""

/* Services, found in /System/Library/Lockdown/Services.plist */

  1. define AMSVC_AFC CFSTR("com.apple.afc")
  2. define AMSVC_BACKUP CFSTR("com.apple.mobilebackup")
  3. define AMSVC_CRASH_REPORT_COPY CFSTR("com.apple.crashreportcopy")
  4. define AMSVC_DEBUG_IMAGE_MOUNT CFSTR("com.apple.mobile.debug_image_mount")
  5. define AMSVC_NOTIFICATION_PROXY CFSTR("com.apple.mobile.notification_proxy")
  6. define AMSVC_PURPLE_TEST CFSTR("com.apple.purpletestr")
  7. define AMSVC_SOFTWARE_UPDATE CFSTR("com.apple.mobile.software_update")
  8. define AMSVC_SYNC CFSTR("com.apple.mobilesync")
  9. define AMSVC_SCREENSHOT CFSTR("com.apple.screenshotr")
  10. define AMSVC_SYSLOG_RELAY CFSTR("com.apple.syslog_relay")
  11. define AMSVC_SYSTEM_PROFILER CFSTR("com.apple.mobile.system_profiler")

typedef unsigned int afc_error_t; typedef unsigned int usbmux_error_t;

struct am_recovery_device;

struct am_device_notification_callback_info { struct am_device *dev; /* 0 device */ unsigned int msg; /* 4 one of ADNCI_MSG_* */ } __PACK;

/* The type of the device restore notification callback functions. * TODO: change to correct type. */ typedef void (*am_restore_device_notification_callback)(struct am_recovery_device *);

/* This is a CoreFoundation object of class AMRecoveryModeDevice. */ struct am_recovery_device { unsigned char unknown0[8]; /* 0 */ am_restore_device_notification_callback callback; /* 8 */ void *user_info; /* 12 */ unsigned char unknown1[12]; /* 16 */ unsigned int readwrite_pipe; /* 28 */ unsigned char read_pipe; /* 32 */ unsigned char write_ctrl_pipe; /* 33 */ unsigned char read_unknown_pipe; /* 34 */ unsigned char write_file_pipe; /* 35 */ unsigned char write_input_pipe; /* 36 */ } __PACK;

/* A CoreFoundation object of class AMRestoreModeDevice. */ struct am_restore_device { unsigned char unknown[32]; int port; } __PACK;

/* The type of the device notification callback function. */ typedef void(*am_device_notification_callback)(struct am_device_notification_callback_info *);

/* The type of the _AMDDeviceAttached function. * TODO: change to correct type. */ typedef void *amd_device_attached_callback;

/* The type of the device restore notification callback functions. * TODO: change to correct type. */ typedef void (*am_restore_device_notification_callback)(struct am_recovery_device *);

struct am_device { unsigned char unknown0[16]; /* 0 - zero */ unsigned int device_id; /* 16 */ unsigned int product_id; /* 20 - set to AMD_IPHONE_PRODUCT_ID */ char *serial; /* 24 - set to AMD_IPHONE_SERIAL */ unsigned int unknown1; /* 28 */ unsigned char unknown2[4]; /* 32 */ unsigned int lockdown_conn; /* 36 */ unsigned char unknown3[8]; /* 40 */ } __PACK;

struct am_device_notification { unsigned int unknown0; /* 0 */ unsigned int unknown1; /* 4 */ unsigned int unknown2; /* 8 */ am_device_notification_callback callback; /* 12 */ unsigned int unknown3; /* 16 */ } __PACK;

struct afc_connection { unsigned int handle; /* 0 */ unsigned int unknown0; /* 4 */ unsigned char unknown1; /* 8 */ unsigned char padding[3]; /* 9 */ unsigned int unknown2; /* 12 */ unsigned int unknown3; /* 16 */ unsigned int unknown4; /* 20 */ unsigned int fs_block_size; /* 24 */ unsigned int sock_block_size; /* 28: always 0x3c */ unsigned int io_timeout; /* 32: from AFCConnectionOpen, usu. 0 */ void *afc_lock; /* 36 */ unsigned int context; /* 40 */ } __PACK;


struct afc_device_info { unsigned char unknown[12]; /* 0 */ } __PACK;

struct afc_directory { unsigned char unknown[0]; /* size unknown */ } __PACK;

struct afc_dictionary { unsigned char unknown[0]; /* size unknown */ } __PACK;

typedef unsigned long long afc_file_ref;

struct usbmux_listener_1 { /* offset value in iTunes */ unsigned int unknown0; /* 0 1 */ unsigned char *unknown1; /* 4 ptr, maybe device? */ amd_device_attached_callback callback; /* 8 _AMDDeviceAttached */ unsigned int unknown3; /* 12 */ unsigned int unknown4; /* 16 */ unsigned int unknown5; /* 20 */ } __PACK;

struct usbmux_listener_2 { unsigned char unknown0[4144]; } __PACK;

struct am_bootloader_control_packet { unsigned char opcode; /* 0 */ unsigned char length; /* 1 */ unsigned char magic[2]; /* 2: 0x34, 0x12 */ unsigned char payload[0]; /* 4 */ } __PACK;

/* ---------------------------------------------------------------------------- * Public routines * ------------------------------------------------------------------------- */

/* Registers a notification with the current run loop. The callback gets * copied into the notification struct, as well as being registered with the * current run loop. dn_unknown3 gets copied into unknown3 in the same. * (Maybe dn_unknown3 is a user info parameter that gets passed as an arg to * the callback?) unused0 and unused1 are both 0 when iTunes calls this. * In iTunes the callback is located from $3db78e-$3dbbaf. * * Returns: * MDERR_OK if successful * MDERR_SYSCALL if CFRunLoopAddSource() failed * MDERR_OUT_OF_MEMORY if we ran out of memory */ __DLLIMPORT mach_error_t AMDeviceNotificationSubscribe(am_device_notification_callback callback, unsigned int unused0, unsigned int unused1, unsigned int dn_unknown3, struct am_device_notification **notification);

/* Connects to the iPhone. Pass in the am_device structure that the * notification callback will give to you. * * Returns: * MDERR_OK if successfully connected * MDERR_SYSCALL if setsockopt() failed * MDERR_QUERY_FAILED if the daemon query failed * MDERR_INVALID_ARGUMENT if USBMuxConnectByPort returned 0xffffffff */ __DLLIMPORT mach_error_t AMDeviceConnect(struct am_device *device);

/* Calls PairingRecordPath() on the given device, than tests whether the path * which that function returns exists. During the initial connect, the path * returned by that function is '/', and so this returns 1. * * Returns: * 0 if the path did not exist * 1 if it did */ __DLLIMPORT mach_error_t AMDeviceIsPaired(struct am_device *device); __DLLIMPORT mach_error_t AMDevicePair(struct am_device *device);

/* iTunes calls this function immediately after testing whether the device is * paired. It creates a pairing file and establishes a Lockdown connection. * * Returns: * MDERR_OK if successful * MDERR_INVALID_ARGUMENT if the supplied device is null * MDERR_DICT_NOT_LOADED if the load_dict() call failed */ __DLLIMPORT mach_error_t AMDeviceValidatePairing(struct am_device *device);

/* Creates a Lockdown session and adjusts the device structure appropriately * to indicate that the session has been started. iTunes calls this function * after validating pairing. * * Returns: * MDERR_OK if successful * MDERR_INVALID_ARGUMENT if the Lockdown conn has not been established * MDERR_DICT_NOT_LOADED if the load_dict() call failed */ __DLLIMPORT mach_error_t AMDeviceStartSession(struct am_device *device);

/* Starts a service and returns a handle that can be used in order to further * access the service. You should stop the session and disconnect before using * the service. iTunes calls this function after starting a session. It starts * the service and the SSL connection. unknown may safely be * NULL (it is when iTunes calls this), but if it is not, then it will be * filled upon function exit. service_name should be one of the AMSVC_* * constants. If the service is AFC (AMSVC_AFC), then the handle is the handle * that will be used for further AFC* calls. * * Returns: * MDERR_OK if successful * MDERR_SYSCALL if the setsockopt() call failed * MDERR_INVALID_ARGUMENT if the Lockdown conn has not been established */ __DLLIMPORT mach_error_t AMDeviceStartService(struct am_device *device, CFStringRef service_name, afc_connection **handle, unsigned int * unknown);

/* Stops a session. You should do this before accessing services. * * Returns: * MDERR_OK if successful * MDERR_INVALID_ARGUMENT if the Lockdown conn has not been established */ __DLLIMPORT mach_error_t AMDeviceStopSession(struct am_device *device);

/* Opens an Apple File Connection. You must start the appropriate service * first with AMDeviceStartService(). In iTunes, io_timeout is 0. * * Returns: * MDERR_OK if successful * MDERR_AFC_OUT_OF_MEMORY if malloc() failed */ __DLLIMPORT afc_error_t AFCConnectionOpen(afc_connection *handle, unsigned int io_timeout, struct afc_connection **conn);

/* Pass in a pointer to an afc_device_info structure. It will be filled. */ __DLLIMPORT afc_error_t AFCDeviceInfoOpen(struct afc_connection *conn, struct afc_dictionary **info);

/* Turns debug mode on if the environment variable AFCDEBUG is set to a numeric * value, or if the file '/AFCDEBUG' is present and contains a value. */

  1. if defined(__APPLE__)

void AFCPlatformInit();

  1. endif

/* Opens a directory on the iPhone. Pass in a pointer in dir to be filled in. * Note that this normally only accesses the iTunes sandbox/partition as the * root, which is /var/root/Media. Pathnames are specified with '/' delimiters * as in Unix style. * * Returns: * MDERR_OK if successful */ __DLLIMPORT afc_error_t AFCDirectoryOpen(struct afc_connection *conn, char *path, struct afc_directory **dir);

/* Acquires the next entry in a directory previously opened with * AFCDirectoryOpen(). When dirent is filled with a NULL value, then the end * of the directory has been reached. '.' and '..' will be returned as the * first two entries in each directory except the root; you may want to skip * over them. * * Returns: * MDERR_OK if successful, even if no entries remain */ __DLLIMPORT afc_error_t AFCDirectoryRead(struct afc_connection *conn/*unsigned int unused*/, struct afc_directory *dir, char **dirent); __DLLIMPORT afc_error_t AFCDirectoryClose(afc_connection *conn, struct afc_directory *dir); __DLLIMPORT afc_error_t AFCDirectoryCreate(afc_connection *conn, char *dirname); __DLLIMPORT afc_error_t AFCRemovePath(afc_connection *conn, char *dirname); __DLLIMPORT afc_error_t AFCRenamePath(afc_connection *conn, char *oldpath, char *newpath);

/* Returns the context field of the given AFC connection. */ __DLLIMPORT unsigned int AFCConnectionGetContext(struct afc_connection *conn);

/* Returns the fs_block_size field of the given AFC connection. */ __DLLIMPORT unsigned int AFCConnectionGetFSBlockSize(struct afc_connection *conn);

/* Returns the io_timeout field of the given AFC connection. In iTunes this is * 0. */ __DLLIMPORT unsigned int AFCConnectionGetIOTimeout(struct afc_connection *conn);

/* Returns the sock_block_size field of the given AFC connection. */ __DLLIMPORT unsigned int AFCConnectionGetSocketBlockSize(struct afc_connection *conn);

/* Closes the given AFC connection. */ __DLLIMPORT afc_error_t AFCConnectionClose(struct afc_connection *conn);

/* Registers for device notifications related to the restore process. unknown0 * is zero when iTunes calls this. In iTunes, * the callbacks are located at: * 1: $3ac68e-$3ac6b1, calls $3ac542(unknown1, arg, 0) * 2: $3ac66a-$3ac68d, calls $3ac542(unknown1, 0, arg) * 3: $3ac762-$3ac785, calls $3ac6b2(unknown1, arg, 0) * 4: $3ac73e-$3ac761, calls $3ac6b2(unknown1, 0, arg) */ __DLLIMPORT unsigned int AMRestoreRegisterForDeviceNotifications( am_restore_device_notification_callback dfu_connect_callback, am_restore_device_notification_callback recovery_connect_callback, am_restore_device_notification_callback dfu_disconnect_callback, am_restore_device_notification_callback recovery_disconnect_callback, unsigned int unknown0, void *user_info);

/* Causes the restore functions to spit out (unhelpful) progress messages to * the file specified by the given path. iTunes always calls this right before * restoring with a path of * "$HOME/Library/Logs/iPhone Updater Logs/iPhoneUpdater X.log", where X is an * unused number. */ __DLLIMPORT unsigned int AMRestoreEnableFileLogging(char *path);

/* Initializes a new option dictionary to default values. Pass the constant * kCFAllocatorDefault as the allocator. The option dictionary looks as * follows: * { * NORImageType => 'production', * AutoBootDelay => 0, * KernelCacheType => 'Release', * UpdateBaseband => true, * DFUFileType => 'RELEASE', * SystemImageType => 'User', * CreateFilesystemPartitions => true, * FlashNOR => true, * RestoreBootArgs => 'rd=md0 nand-enable-reformat=1 -progress' * BootImageType => 'User' * } * * Returns: * the option dictionary if successful * NULL if out of memory */ __DLLIMPORT CFMutableDictionaryRef AMRestoreCreateDefaultOptions(CFAllocatorRef allocator);

/* ---------------------------------------------------------------------------- * Less-documented public routines * ------------------------------------------------------------------------- */

/* mode 2 = read, mode 3 = write; unknown = 0 */ __DLLIMPORT afc_error_t AFCFileRefOpen(struct afc_connection *conn, char *path, unsigned long long int mode, afc_file_ref *ref); __DLLIMPORT afc_error_t AFCFileRefRead(struct afc_connection *conn, afc_file_ref ref, void *buf, unsigned int *len); __DLLIMPORT afc_error_t AFCFileRefWrite(struct afc_connection *conn, afc_file_ref ref, void *buf, unsigned int len); __DLLIMPORT afc_error_t AFCFileRefSeek(struct afc_connection *conn, afc_file_ref ref, unsigned long long offset1, unsigned long long offset2); __DLLIMPORT afc_error_t AFCFileRefClose(struct afc_connection *conn, afc_file_ref ref); __DLLIMPORT afc_error_t AFCFileInfoOpen(struct afc_connection *conn, char *path, struct afc_dictionary **info); __DLLIMPORT afc_error_t AFCKeyValueRead(struct afc_dictionary *dict, char **key, char ** val); __DLLIMPORT afc_error_t AFCKeyValueClose(struct afc_dictionary *dict); __DLLIMPORT unsigned int AMRestorePerformRecoveryModeRestore(struct am_recovery_device * rdev, CFDictionaryRef opts, void *callback, void *user_info); __DLLIMPORT unsigned int AMRestorePerformRestoreModeRestore(struct am_restore_device * rdev, CFDictionaryRef opts, void *callback, void *user_info); __DLLIMPORT struct am_restore_device *AMRestoreModeDeviceCreate(unsigned int unknown0, unsigned int connection_id, unsigned int unknown1); __DLLIMPORT unsigned int AMRestoreCreatePathsForBundle(CFStringRef restore_bundle_path, CFStringRef kernel_cache_type, CFStringRef boot_image_type, unsigned int unknown0, CFStringRef *firmware_dir_path, CFStringRef * kernelcache_restore_path, unsigned int unknown1, CFStringRef * ramdisk_path); __DLLIMPORT unsigned int AMRestoreModeDeviceReboot(struct am_restore_device *rdev); // Added by JB 30.07.2008 __DLLIMPORT unsigned int AMDeviceGetConnectionID(struct am_device *device); __DLLIMPORT mach_error_t AMDeviceEnterRecovery(struct am_device *device); __DLLIMPORT mach_error_t AMDeviceDisconnect(struct am_device *device); __DLLIMPORT mach_error_t AMDeviceRetain(struct am_device *device); __DLLIMPORT mach_error_t AMDeviceRelease(struct am_device *device); __DLLIMPORT CFStringRef AMDeviceCopyValue(struct am_device *device, unsigned int, CFStringRef cfstring); __DLLIMPORT CFStringRef AMDeviceCopyDeviceIdentifier(struct am_device *device); __DLLIMPORT mach_error_t AMDShutdownNotificationProxy(void *);

/*edits by geohot*/ __DLLIMPORT mach_error_t AMDeviceDeactivate(struct am_device *device); __DLLIMPORT mach_error_t AMDeviceActivate(struct am_device *device, CFDictionaryRef dict); __DLLIMPORT mach_error_t AMDeviceRemoveValue(struct am_device *device, unsigned int, CFStringRef cfstring);

/* ---------------------------------------------------------------------------- * Semi-private routines * ------------------------------------------------------------------------- */

/* Pass in a usbmux_listener_1 structure and a usbmux_listener_2 structure * pointer, which will be filled with the resulting usbmux_listener_2. * * Returns: * MDERR_OK if completed successfully * MDERR_USBMUX_ARG_NULL if one of the arguments was NULL * MDERR_USBMUX_FAILED if the listener was not created successfully */ __DLLIMPORT usbmux_error_t USBMuxListenerCreate(struct usbmux_listener_1 *esi_fp8, struct usbmux_listener_2 **eax_fp12);

/* ---------------------------------------------------------------------------- * Less-documented semi-private routines * ------------------------------------------------------------------------- */ __DLLIMPORT usbmux_error_t USBMuxListenerHandleData(void *);

/* ---------------------------------------------------------------------------- * Private routines - here be dragons * ------------------------------------------------------------------------- */

/* AMRestorePerformRestoreModeRestore() calls this function with a dictionary * in order to perform certain special restore operations * (RESTORED_OPERATION_*). It is thought that this function might enable * significant access to the phone. */

/* typedef unsigned int (*t_performOperation)(struct am_restore_device *rdev, CFDictionaryRef op) __attribute__ ((regparm(2))); t_performOperation _performOperation = (t_performOperation)0x3c39fa4b; */

/* ---------------------------------------------------------------------------- * Less-documented private routines * ------------------------------------------------------------------------- */


/* typedef int (*t_socketForPort)(struct am_restore_device *rdev, unsigned int port) __attribute__ ((regparm(2))); t_socketForPort _socketForPort = (t_socketForPort)(void *)0x3c39f36c;

typedef void (*t_restored_send_message)(int port, CFDictionaryRef msg); t_restored_send_message _restored_send_message = (t_restored_send_message)0x3c3a4e40;

typedef CFDictionaryRef (*t_restored_receive_message)(int port); t_restored_receive_message _restored_receive_message = (t_restored_receive_message)0x3c3a4d40;

typedef unsigned int (*t_sendControlPacket)(struct am_recovery_device *rdev, unsigned int msg1, unsigned int msg2, unsigned int unknown0, unsigned int *unknown1, unsigned char *unknown2) __attribute__ ((regparm(3))); t_sendControlPacket _sendControlPacket = (t_sendControlPacket)0x3c3a3da3;;

typedef unsigned int (*t_sendCommandToDevice)(struct am_recovery_device *rdev, CFStringRef cmd) __attribute__ ((regparm(2))); t_sendCommandToDevice _sendCommandToDevice = (t_sendCommandToDevice)0x3c3a3e3b;

typedef unsigned int (*t_AMRUSBInterfaceReadPipe)(unsigned int readwrite_pipe, unsigned int read_pipe, unsigned char *data, unsigned int *len); t_AMRUSBInterfaceReadPipe _AMRUSBInterfaceReadPipe = (t_AMRUSBInterfaceReadPipe)0x3c3a27e8;

typedef unsigned int (*t_AMRUSBInterfaceWritePipe)(unsigned int readwrite_pipe, unsigned int write_pipe, void *data, unsigned int len); t_AMRUSBInterfaceWritePipe _AMRUSBInterfaceWritePipe = (t_AMRUSBInterfaceWritePipe)0x3c3a27cb; */

int performOperation(am_restore_device *rdev, CFMutableDictionaryRef message); int socketForPort(am_restore_device *rdev, unsigned int portnum); int sendCommandToDevice(am_recovery_device *rdev, CFStringRef cfs, int block); int sendFileToDevice(am_recovery_device *rdev, CFStringRef filename);


  1. ifdef __cplusplus

}

  1. endif
  1. endif

Libraries Implementations

Need to be writed...

USBMux Protocol

Resources

The dev team's page on the topic [1] iFuse

Retrieved from "https://www.theiphonewiki.com/w/index.php?title=Normal_Mode&oldid=1699"