Friday, 1 February 2013

Hooking objective-c internals using the Captain Hook framework.

One of the fun things to do with a Jailbroken iPhone is to install custom themes using the "WinterBoard" application.
This allows you to install themes such as: Auxo which customises the application switcher bar or Boss.ios which alters the whole look of the interface.

How does "Winterboard" work?

The "WinterBoard" application works by "hooking" the existing internal classes using the Objective-C Runtime Library. This library is loaded by all Objective-C applications to support the dynamic features of the language which means that we can utlilise is to perform our own alterations to the OS and applications.
This allows for the alteration of icons, sounds and textures without having to touch the originals supplied with the device. This means that you can alter the device without the risk of breaking the device.

The CaptainHook framework

This is a header file created by Ryan Petrich( to assist with the creation of hooking libraries using the Objective-C runtime. This provides a functions to assist in the setting up of custom hooking code. Documentation is a little scant so hopefully this blog can help you begin to create your own hooks.

Getting started

I've altered the sample code provided at the Github as the function used has been depreciated by Apple
hook source code and a makefile
#import <CaptainHook/CaptainHook.h>
CHDeclareClass(NSString); //set up the Captain Hook Library

//function called when hook is encountered
CHMethod(4, void, NSString, writeToFile, NSString *, path,  
         atomically, BOOL, useAuxiliaryFile, encoding,  
         NSStringEncoding, end, error, NSError **, error) 
  NSLog(@"Writing string to %@: %@", path, self);
  //send received arguments to the original class
  CHSuper(4, NSString, writeToFile, path, atomically,
  useAuxiliaryFile, encoding, end, error, error);

//create the hook
  CHLoadClass(NSString); //setup the class
  //hook the chosen method
  CHHook(4, NSString, writeToFile, atomically, encoding, 

Heres a sample program you can test it with:
link to test program and makefile
#import <Foundation/Foundation.h>
#import <Foundation/NSString.h>

int main(void) {
  NSAutoreleasePool *pool = \
    [[NSAutoreleasePool alloc] init];
  NSString *testString = @"Hello, I am the test string";
  [pool release];
  return 0;


Compiling works on OS X with xCode 4.x and iOS SDK version 6.0 in the default library locations.
Copy the compiled "testhook" and "stringHook.dylib" to your device. SSH in, export DYLD_INSERT_LIBRARIES and then execute "testhook" e.g:
  desktop$ scp ./hooktest ./stringHook.dylib \
root@<device ip>:/var/root/
  desktop$ ssh root@<device ip>
  device # export \
  device # /var/root/hooktest

And you should see:
  2013-02-01 21:40:58.710 hooktest[562:707] Writing string to   
  test.txt: Hello, I am the test string
Which only works for command line apps as export DYLD... does not get performed by SpringBoard

A bit of explanation

The CHMethod function declaration is:
  CHMethod(number of inputs, return type, class name, name1, type1, 
  arg1, name2, type2, arg2 ...(number of inputs));

An easy way to fill this method is to take the method definition, and fill it in left to right e.g.
  [NSString writeToFile: atomically: encoding: error:]
  -(BOOL)writeToFile:(NSString *)path atomically:   
  (BOOL)useAuxiliaryFile encoding:(NSStringEncoding)enc error   
  (NSError **)error
translates to:
  CHMethod(4, void, NSString, writeToFile, NSString *, path,    
  atomically, BOOL, useAuxiliaryFile, encoding, NSStringEncoding, 
end, error, NSError **, error)
We set the return type to void as for the example we don't return anything

The function declaration of CHSuper and CHHook are:
CHSuper(number of inputs, class name, name1, arg1, name2,
arg2 ...(number of inputs)

CHHook(number of inputs, class name,name1,name2,
...(num of inputs)

Other ways of inserting the injection library

Using launchctl seems to be a great way.
launchctl setenv DYLD_INSERT_LIBRARIES "/path/to/dylib"
which can be used for individual SpringBoard apps
or you can insert this plist key into one of the plists in "/System/Library/LaunchDaemons/"
although be careful! i screwed up my SpringBoard.plist editing it which caused the SpringBoard to stop loading(i.e no icons), so make a backup of the file just to be sure.

reload the plist using
launchctl unload <chosen plist>
then reload
launchctl load <chosen plist>

Another easy method is to install MobileSubstrate and copy the dylib to "/Library/MobileSubstrate/DynamicLibraries" and reload the SpringBoard. MobileSubstrate loads all the dylibs in this folder automatically.

Heres another piece of sample hooking code i created playing this stuff:
This changes the status bar each time a touch is detected.

A great use of this hooking in security testing has been recently released by Jeremy Allen which uses it to disable certificate verification.
So play around with it and see what fun you can have.

No comments:

Post a Comment