Dev:Cydia Substrate

Languages: English &bull; français

Cydia Substrate (formerly called MobileSubstrate) is the de facto framework that allows 3rd-party developers to provide run-time patches (“Cydia Substrate extensions”) to system functions, similar to Application Enhancer on the OS X.

saurik has written a whole website of documentation for Substrate.

Cydia Substrate consists of 3 major components: MobileHooker, MobileLoader and safe mode.

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

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. 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 is 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 iOS by default a memory page cannot be simultaneously writable and executable, a kernel patch must be applied for MSHookFunction to work. (Any public jailbreak should have one.)

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

It is also possible to get references to classes' ivars via MSHookIvar when not possible via instance methods.

Example code
Using MSHookFunction:

Using MSHookMessageEx:

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

Using MSHookFunction to hook private functions (in this case a C++ Method):

Because we want the pointer to a private symbol we have to use nlist. However you should not be doing it this way, as it is not portable to other platforms and later versions of iOS. MSGetImageByName and MSFindSymbol provide the same functionality and are portable.

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

MobileLoader will first load itself into the run application using DYLD_INSERT_LIBRARIES 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.

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


 * 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, the plist would look like

 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  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:

 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  Filter Bundles  com.apple.UIKit 

You can use CoreFoundationVersion key and specify lower- and upper-bounds. When two values are in the array, the first is treated as greater-than-or-equal-to rule, while the second is a less-than rule. The following example shows loading restricted to firmwares from 4.0 to 4.3 only:

<?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"> Filter Bundles com.apple.UIKit CoreFoundationVersion  550.32      675.00  You can also include both Executables and Bundle filters to match both executables and applications that link to specific bundles you want.

<?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"> Filter Executables  mediaserverd  Bundles  com.apple.MobileSMS   net.whatsapp.WhatsApp 

As of iOS 9.0, the filter plist must exist. Dylibs without a corresponding plist will not be loaded. To replicate the previous effect of no filter plist causing the dylib to be loaded into all processes, set your filter to the bundle.

For setuid apps, since almost all environment variables are discarded, the developer of the app must explicitly perform  within   to let MobileLoader run. This is not recommended, since most extensions do not expect to be running within a root process, and can have unexpected behavior (such as writing a file with permissions that would disallow it from being read by non-root processes). It would be a better choice to design the app to run as mobile, with a helper process performing root operations.

In addition, MobileLoader also hooks nlist</tt> to improve its performance, and defines several signal handlers for safe mode.

Safe mode
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:
 * SIGABRT
 * SIGILL
 * SIGBUS
 * SIGSEGV
 * SIGSYS