MobileSubstrate - iPhone Development Wiki http://www.iphonedevwiki.net/index.php?title=MobileSubstrat...

MobileSubstrate
From iPhone Development Wiki

MobileSubstrate is the de facto framework that allows 3rd-party developers to provide

run-time patches (“MobileSubstrate extensions”) to system functions, similar to MobileSubstrate
Application Enhancer (http://www.unsanity.com/haxies/ape) on the OS X. Cydia Package
MobileSubstrate consists of 3 major components: MobileHooker, MobileLoader and safe Developer saurik
mode.
Package ID mobilesubstrate
Latest Version 0.9.3087-1

Contents
1 MobileHooker
1.1 Example code
2 MobileLoader
3 Safe mode

MobileHooker
MobileHooker is used to replace system functions. This process is known as hooking. There are 2 APIs that one would use:

IMP MSHookMessage(Class class, SEL selector, IMP replacement, const char* prefix); // prefix should be NULL.
void MSHookMessageEx(Class class, SEL selector, IMP replacement, IMP *result);
void MSHookFunction(void* function, void* replacement, void** p_original);

MSHookMessage() will replace the implementation of the Objective-C message -[class selector] by replacement, and return the original
implementation. To hook a class method, provide the meta class retrieved from objc_getMetaClass in the MSHookeMessage(Ex) call and see
example note below. This dynamic replacement is in fact a feature of Objective-C, and can be done using method_setImplementation
(http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html#//apple_ref/c/func
/method_setImplementation) . MSHookMessage() is not thread-safe and has been deprecated in favor of MSHookMessageEx()

MSHookFunction() is like MSHookMessage() but is for C/C++ functions. The replacement must be done at assembly level. Conceptually,
MSHookFunction() will write instructions that jumps to the replacement function, and allocate some bytes on a custom memory location,
which has the original cut-out instructions and a jump to the rest of the hooked function. Since on the iPhoneOS by default a memory page
cannot be simultaneously writable and executable, a kernel patch must be applied for MSHookFunction() to work.

As of the latest version of MobileSubstrate, MSHookMessage() also requires a kernel patch for supercall closures to hook all methods
properly.

Example code

Using MSHookFunction:

static void (*original_CFShow)(CFTypeRef obj); // a function pointer to store the original CFShow().
void replaced_CFShow(CFTypeRef obj) { // our replacement of CFShow().
printf("Calling original CFShow(%p)...", obj);
original_CFShow(obj); // calls the original CFShow.
printf(" done.\n");
}
...
// hook CFShow to our own implementation.
MSHookFunction(CFShow, replaced_CFShow, &original_CFShow);
// From now on any call to CFShow will pass through replaced_CFShow first.
...
CFShow(CFSTR("test"));

Using MSHookMessageEx:

1 of 3 5/6/11 3:00 PM
MobileSubstrate - iPhone Development Wiki http://www.iphonedevwiki.net/index.php?title=MobileSubstrat...

static IMP original_UIView_setFrame_;

void replaced_UIView_setFrame_(UIView* self, SEL _cmd, CGRect frame) { // Note the implicit self and _cmd parameters are needed explicitly here.
CGRect originalFrame = self.frame;
NSLog("Changing frame of %p from %@ to %@", self, NSStringFromCGRect(originalFrame), NSStringFromCGRect(frame));
original_UIView_setFrame_(self, _cmd, frame); // Remember to pass self and _cmd.
}
...
MSHookMessageEx([UIView class], @selector(setFrame:), (IMP)replaced_UIView_setFrame_, (IMP *)&original_UIView_setFrame_);
...
myView.frame = CGRectMake(0, 0, 100, 100);

Note that if you are hooking a class method, you have to put a meta-class in the class argument, e.g.

MSHookMessageEx(objc_getMetaClass("UIView"), @selector(commitAnimations), replaced_UIView_commitAnimations, (IMP *)&original_UIView_commitAnimations

MobileLoader
MobileLoader loads 3rd-party patching code into the running application.

MobileLoader will first load itself into the run application using DYLD_INSERT_LIBRARIES (http://koichitamura.blogspot.com/2008/11
/hooking-library-calls-on-mac.html) environment variable. Then it looks for all dynamic libraries in the directory /Library
/MobileSubstrate/DynamicLibraries/, and dlopen them. An extension should use constructor code to perform any works, e.g.

...
// The attribute forces this function to be called on load.
__attribute__((constructor))
static void initialize() {
NSLog(@"MyExt: Loaded");
MSHookFunction(CFShow, replaced_CFShow, &original_CFShow);
}

Developers may add filters to restrict whether the extension should be loaded or not. Filters are implemented as plist that lives beside the
dylib. If the dylib is named foo.dylib, then the filter should be named foo.plist. The filter should be a dictionary with key Filter, which is
another dictionaries that can contain these keys:

CoreFoundationVersion (array): The extension is loaded only if the version of CoreFoundation.framework is above the specified
values. Currently, only the first 2 values are checked.
Firmware 2.0 2.1 2.2 3.0 3.1 3.2
CF version 478.23 478.26 478.29 478.47 478.52 478.61

Bundles (array): The extension is loaded only if the bundle-ID of the running application matches the list.
Classes (array): The extension is loaded only if the one of the specified objective-C classes is implemented in the application.
Executables (array): The extension is loaded only if one of the executable names matches the running application. This is required to
hook things that have no other identifiable characteristics.

For example, to restrict the extension only load in SpringBoard, the plist would look like

Filter = {
Bundles = (com.apple.springboard);
};

You can also use this method to restrict the extension to only load into applications that link to a specific bundle, such as UIKit. For example:

Filter = {
Bundles = (com.apple.UIKit);
};

In addition, MobileLoader also hooks nlist() to improve its performance, and defines several signal handlers for safe mode.

For setuid apps, since all inserted environment variables are ignored, the developer of the App must explicitly dlopen("/Library
/MobileSubstrate/MobileSubstrate.dylib") to let MobileLoader run.

Safe mode

2 of 3 5/6/11 3:00 PM
MobileSubstrate - iPhone Development Wiki http://www.iphonedevwiki.net/index.php?title=MobileSubstrat...

When a extension crashed the SpringBoard, MobileLoader will catch that and put the device into safe mode. In safe mode all 3rd-party
extensions will be disabled.

The following signals will invoke safe mode:

SIGTRAP
SIGABRT
SIGILL
SIGBUS
SIGSEGV
SIGSYS

Runtime patching mechanisms [hide]

MobileSubstrate • Mobile Enhancer (PseudoSubstrate) • Rock Extensions

Library Subdirectories [hide]

/System/Library Frameworks • Internet Plug-Ins • PreferenceBundles • PrivateFrameworks • PublishingBundles • SearchBundles • SpringBoardPlugins
/Library Libactivator • MobileSubstrate • PreferenceLoader
~/Library SBSettings
Retrieved from "http://www.iphonedevwiki.net/index.php/MobileSubstrate"
Categories: Cydia packages | Directories in /Library

This page was last modified on 2 December 2010, at 14:15.

3 of 3 5/6/11 3:00 PM