Jeremy Johnstone

A new geek term for the masses. Instead of calling the most kickass phone ever invented an “iPhone”, from now on it should be referred to as a “trouser mac”.

This evening I decided today would be the day I upgraded to 1.0.2. Despite a few hiccups with the restoration, the update proceeded and my iPhone was now running Apple’s latest and greatest release. Sadly, that also meant my iPhone was now pristine again without any of the apps I have come to love on it. After hearing about the new Installer.app GUI installer, I had to give it a shot.

This is about as simple of a howto as one could get, the steps to getting Installer.app running (which opens the door for SSH, Terminal, etc) is as follows:

1. Download the Installer.app GUI installer from here.
2. Run the application and follow the onscreen instructions (connecting phone, shutting down iTunes, selecting current phone firmware revision).
3. Sit back and wait 2-3 minutes. It literally does everything else for you!

No more do you need long howtos, no more do you need to worry about missing steps. Just sit back and let the GUI app do it’s business and you are good to go. I’m still a little irritated they haven’t opened up the source on the app, but otherwise the process couldn’t be simpler. If you haven’t hacked your phone yet, what are you waiting for?

In the first post of this howto, I talked you through getting full access to your iPhone and a basic SSH server running. If you haven’t read Part #1 yet, please do so before continuing here. In this post, we will actually get our toolchain setup as well as install a few more useful pieces of software.

The first thing I will talk you through is replacing DropBear. We will install OpenSSH2 onto the phone which will provide us with the full suite of SSH functionality. Follow these simple steps to upgrade:

1. Download the openssh iPhone package and extract it into ~/phonedmg/openssh
2. Download the iPhone binkit and extract it into ~/phonedmg/binkit
3. Fire up iPHUC and run the following commands (you will get an error about the rmdir, ignore it as it did it’s job):

   mkdir /etc/ssh2
   putfile /Users/(your username)/phonedmg/openssh/etc/ssh2/ssh2_config /etc/ssh2/ssh2_config
   putfile /Users/(your username)/phonedmg/openssh/etc/ssh2/sshd2_config /etc/ssh2/sshd2_config
   
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/scp2 /usr/bin/scp2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/sftp-server2 /usr/bin/sftp-server2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/sftp2 /usr/bin/sftp2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/ssh-add2 /usr/bin/ssh-add2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/ssh-agent2 /usr/bin/ssh-agent2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/ssh-keygen2 /usr/bin/ssh-keygen2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/ssh-probe2 /usr/bin/ssh-probe2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/ssh-signer2 /usr/bin/ssh-signer2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/ssh2 /usr/bin/ssh2
   putfile /Users/(your username)/phonedmg/openssh/usr/bin/sshd2 /usr/bin/sshd2
   putfile /Users/(your username)/phonedmg/openssh/System/Library/LaunchDaemons/com.sshd.plist /System/Library/LaunchDaemons/com.sshd.plist
   
   putfile /Users/(your username)/phonedmg/binkit/usr/bin/scp /usr/bin/scp
   putfile /Users/(your username)/phonedmg/binkit/bin/ls /usr/bin/ls
   putfile /Users/(your username)/phonedmg/binkit/usr/lib/libarmfp.dylib  /usr/lib/libarmfp.dylib
   
   rmdir /System/Library/LaunchDaemons/au.asn.ucc.matt.dropbear.plist
   

4. Now, ssh into your phone (you will be connecting to the dropbear server still) and do the following:

   -sh-3.2# chmod 555 /bin/ls /usr/bin/*
   -sh-3.2# ssh-keygen2 -P -t dsa -c "DSA hostkey" /etc/ssh2/hostkey
   -sh-3.2# launchctl load /System/Library/LaunchDaemons/com.sshd.plist
   

5. Now reboot your phone and make sure you still have ssh access.

Now that you have a good SSH server on your phone, it’s time to add in a bunch of standard Unix commands. You do this by running the following commands on your Mac:

$ cd ~/phonedmg/binkit
$ scp -R bin sbin usr libexec root@(iphone IP):/

After doing this, you should have things like grep, uname, ps, etc on your iPhone. Try them out to be sure. As a quick exercise, now that you have a full blown SSH server on your iPhone and basic apps like vim, you should consider disabling password based authentication and put your SSH key on it. Much more secure, IMHO. If you need help with this, ping me.

The next thing we will do is get our toolchain working. My preference is to build the toolchain from source (easier to keep up to date). This can be time consuming though, so if you are the impatient type, do a Yahoo! search for “iphonetoolchain dmg”. I haven’t tested this approach, so I won’t provide any direct links (as they may rapidly change). To build the toolchain, do the following:

1. Create a home for the toolchain source, my suggestion is ~/phonedmg/toolchain and the examples will follow as such.
2. Install libstreams onto your box by running:

   sudo port install libstreams
   

3. We now need to decrypt the firmware. Due to the fact I am uncertain the legality of posting the firmware encryption key, I am linking you to the instructions here. After decrypting, you should have a file named decrypted.dmg. Mount this disk image.
4. Now copy the files inside the mounted disk image into your toolchain directory by doing the following:

   mkdir ~/phonedmg/toolchain/heavenly
   sudo cp -R /Volumes/Heavenly1A543a.UserBundle/* ~/phonedmg/toolchain/heavenly/
   

5. Now checkout the toolchain code from the public subversion repo

   cd ~/phonedmg/toolchain
   svn checkout svn://svn.berlios.de/iphone-binutils/trunk
   

6. Now we need to actually build the toolchain itself. First we:

   cd ~/phonedmg/toolchain/trunk
   ./configure --with-heavenly=/Users/(your username)/phonedmg/toolchain/heavenly/
   

   Then we need to fix a problem in the generated makefile by editing line 34 and making it read:

   cd llvm-2.0 && $(MAKE) ENABLE_OPTIMIZED=1 install
   

   and then following that we run _sudo make_ (note the sudo is apparently required).

Now that we have our toolchain setup, let’s build the most useful app I have found so far. This application is a Terminal.app like application for the iPhone. It provides a GUI interface to running shell commands on the phone and is immensely useful for things like SSH (outbound from the phone). The app also has good polish for such an early edition and thus is a good example of what can be done. Follow these steps for getting it running on your iPhone:

1. First things first, we need to download the source code to the app. We do this by:

   mkdir ~/phonedmg/apps
   cd ~/phonedmg/apps
   svn checkout http://mobileterminal.googlecode.com/svn/trunk/ mobileterminal
   

2. Now we need to download a header file, UITextTraitsClientProtocol.h, missing from the toolchain and put it in /Developer/SDKs/iPhone/include/UIKit/
3. Next we fake a couple files to make things happy by doing the following:

   sudo touch /Developer/SDKs/iPhone/include/UIKit/NSObject.h
   sudo touch /Developer/SDKs/iPhone/include/LayerKit/NSObject.h
   

4. Now run _make_ and _make package_
5. Assuming all goes well (I got some warnings, but it compiled), copy the resulting Terminal.app bundle to your phone:

   scp -r Terminal.app root@(iPhone IP):/Applications/
   

6. Now reboot your iPhone and now you should see the new app available to use. Here’s a screenshot of what it looks like:
   

That completes our howto and I would love to thank the numerous devs around the world who have made all this possible. Now that you have a toolchain and an extremely useful sample app, let’s see what apps you can create! If you make something, please be sure and let me know.

P.S. - A helpful tip in regards to the terminal app, to do a control key sequence use the “bullet” key which can be found by pressing the 123 key, then the #+= key (center far right of that last keyboard). Also, to hide the keyboard, simply tap the screen (and again to bring it back up).

After getting numerous inquiries from coworkers and friends, decided to write a cohesive howto guide on getting custom apps on your iPhone. Yes, there are numerous sources of information all over the net, but I haven’t seen (keyword, I haven’t, maybe you have) a howto which covers everything from start to finish. This will be a multi-part series (mainly because I don’t want to type so much write now) so stay tuned for the complete guide. For all of these instructions, I am going to assume you are on a Mac. I’ve not seen any way to build apps using the toolchain on Windows and since that is the whole point of this howto series, I won’t go into any Windows related stuff (sorry!).

First things first, you need to get access into the iPhone outside of normal Apple channels. I’ve tried numerous different methods with varying levels of success, but the one I have found easiest is to use Jailbreak combined with iPHUC. Yes, yes, you can do all of it with just iPHUC now, but I have found Jailbreak to be far easier and less error prone to get out of the chroot jail. So, first things first, you need to download a few things:

Jailbreak
iPhone Restore Image

The restore image is really a zipfile, so if it didn’t uncompress automatically, then rename the file with a .zip extension and extract it. Now create a directory somewhere (like your home dir) named ” phonedmg “. Inside this directory put the _contents_ of the iPhone1,1_1 from the extracted restore image. Make sure you put the contents (aka two disk images, a directory, and two files) and not the directory itself! Now also extract Jailbreak and put it’s contents there too. Next you are going to run Jailbreak (if I need to tell you how to run it, you should really stop here). Follow the instructions it gives to put the phone in restore mode and a couple moments later your phone should now be fully accessible. If you are curious the steps it is performing behind the scenes, read this twiki page on “How to escape Jail” which is more or less the same steps (except it does it in a different order, but essentially the same thing). I chose to use the automated method as the steps are a bit tedious and there is no perceived benefit I can tell from using the manual steps.

Now that we have complete access to the phone’s filesystem, we will install a basic SSH server to help us with the bootstrap process. The first step is to download and compile iPHUC. The build process is as follows (lifted from here, only reprinted to keep you from having to jump around):

1. Download and install MacPorts
2. Open Terminal and issue the following commands (these instructions assume you have xcode developer tools installed and put your phone software in ~/phonedmg):

   sudo port selfupdate
   sudo port install readline
   cd ~/phonedmg/
   mkdir tools-src
   cd tools-src/
   svn co http://iphonesvn.halifrag.com/svn/iPhone iphuc-src
   cd ./iphuc-src/trunk/iPHUC/
   

3. Get the most recent version of MobileDevice.h and save a copy to ‘MobileDevice.h’ in the iPHUC directory
4. Patch NormalInterface.cpp with the following patch:

   Index: NormalInterface.cpp
   ===================================================================
   --- NormalInterface.cpp ( revision 8 )
   +++ NormalInterface.cpp ( working copy )
   @@ -1,4 +1,4 @@
   -#include "normalinterface.h"
   +#include "NormalInterface.h"
    #include "Shell.h"
   
    int n_pwd(string *args, struct shell_state *sh)
   

5. Build iPHUC via the following (ignore warnings if everything builds):
   ./autogen.sh && ./configure –with-readline=/opt/local && make
6. Copy iPHUC into your phonedmg folder (not required, but I like to keep everything in one convenient spot)

Now that you have built iPHUC, it’s time to get shell access on the phone. We first need to download dropbear for iPhone. Ultimately, dropbear isn’t the SSH server we will stay with, it’s just easier to get it going first. After downloading it, extract it into ~/phonedmg/dropbear. We also need to create ourselves some SSH host keys which we can do by:

1. Download dropbear source code
2. Do the normal ./configure && make routine (no need to install, we just need one thing from it)
3. Generate the host keys via:

   ./dropbearkey -t rsa -f dropbear_rsa_host_key
   ./dropbearkey -t dss -f dropbear_dss_host_key
   

4. Copy these two files to your ~/phonedmg folder and then you can delete the dropbear stuff you downloaded in this part as it’s no longer needed

With that completed, now let us upload the stuff to the phone. We do this by firing up iPHUC and following these steps:

1. Upon running iPHUC, you should see something like the following (if you don’t, then leave a comment or contact me and hopefully I can help you):

   localhost:~/phonedmg $ ./iphuc
   iphuc 0.5.0
   >> By The iPhoneDev Team: nightwatch geohot ixtli warren nall mjc operator
   initPrivateFunctions: this is still not clean.  Architecture: i386
   AMDeviceNotificationSubscribe: 0
   CFRunLoop: Waiting for iPhone.
   notification: iPhone attached.
   AMDeviceConnect: 0
   AMDeviceIsPaired: 1
   AMDeviceValidatePairing: 0
   AMDeviceStartSession: 0
   AMDeviceStartService AFC: 0
   AFCConnectionOpen: 0
   AFCPlatformInit: (no retval)
   notification: Entering shell in Normal Mode.
   shell: Entering loop.
   (iPHUC) /:
   

2. Now we need to tell iPHUC to use the special AFC by typing in ” setafc com.apple.afc2 “. You should see something like the following:

   (iPHUC) /: setafc com.apple.afc2
   AMDeviceStartService AFC: 0
   AFCConnectionOpen: 0
   

3. If that’s what you see, then do an ls and make sure you see things resembling a normal root filesystem path (/Applications, /usr, /System, etc). Again, if not, you got a problem.
4. Now let’s get some files in various places which we need. Execute the following commands:

   getfile /System/Library/LaunchDaemons/com.apple.update.plist com.apple.update.plist.original
   getfile /usr/sbin/update update.original
   

5. Now that we have originals of those files, we can upload our files to the phone by doing the following commands back in iPHUC:

   putfile /Users/(your username)/phonedmg/dropbear/sh /bin/sh
   putfile /Users/(your username)/phonedmg/dropbear/chmod /bin/chmod
   putfile /Users/(your username)/phonedmg/dropbear/chmod /usr/sbin/update
   putfile /Users/(your username)/phonedmg/dropbear/dropbear /usr/bin/dropbear
   putfile /Users/(your username)/phonedmg/dropbear/au.asn.ucc.matt.dropbear.plist /System/Library/LaunchDaemons/au.asn.ucc.matt.dropbear.plist
   putfile /Users/(your username)/phonedmg/dropbear/com.apple.update.plist.hacked /System/Library/LaunchDaemons/com.apple.update.plist
   mkdir /etc/dropbear
   putfile /Users/(your username)/phonedmg/dropbear_rsa_host_key /etc/dropbear/dropbear_rsa_host_key
   putfile /Users/(your username)/phonedmg/dropbear_dss_host_key /etc/dropbear/dropbear_dss_host_key
   

6. Now we need to reboot the phone _twice_. The first time will set execute permissions on our binaries, the second time will actually start the ssh daemon (since it will now be executable). You do know how to reboot your phone, right?
7. Now we need to make sure SSH is working. First make sure you are associated with a wifi network on the phone and get the IP address (logically your laptop and phone need to be on the same wifi network). Then SSH to the phone using username ” root ” and password ” dottie “. If all is well, then we will want to restore the update daemon back to normal. Do this via the following two commands in iPHUC:

   putfile /Users/(your username)/phonedmg/com.apple.update.plist.original /System/Library/LaunchDaemons/com.apple.update.plist
   putfile /Users/(your username)/phonedmg/update.original /usr/sbin/update
   

8. Now, before continuing any further, we need to secure the phone a bit. Since everyone who has hacked an iPhone (and many who haven’t) now knows your root password, let’s fix that. Run the following command in a normal terminal window:
   perl -e ‘print crypt(”MYPASSWORD”, “XX”);’

   Replacing MYPASSWORD with a password and XX with any random two letters (it’s the salt). The easiest way to replace the passwords is to do a “getfile /etc/master.passwd master.passwd.original” in iPHUC, edit both the root and mobile users’ passwords, and the do a “putfile /Users/(your username)/master.passwd.original /etc/master.passwd”.

With that, this first part of the series is now complete. You have successfully hacked your iPhone and got an SSH server running on it. In the next part of the series, I will detail how to install a better SSH server, get basic unix commands on the phone, setup your toolchain/build environment, and then build and install a terminal GUI app on the phone.