Creating iLiberty Payloads

From ModMyiFone - Wiki

Overall Processing

Pre-processing

• Front end application select the set of payloads, creates the payload.zip file. • A sh style options file (options.inc) is also created. • Using AFC, the payload.zip file and the option file are moved to the phone /var/{root,mobile}/Media directory. • Bootstrapped the ramdisk (pass-1)

Pass-1

The ramdisk will boot and perform only the following tasks:
 • Do nothing is payload not found. • Jailbreak • Enable AFC2 • Perform minimal setup for pass-2: • Install the pass2.plist in LaunchDaemon • Create the minimal environment in /bin2 • Place required files in /etc (profile and termcap) • Temporarily disable CommCenter and Springboard • Erase any “process” communication file (.MSG) • Do the necessary pass-1 cleanup • Reboot the phone

Pass-2

• The pass2.plist will start the pass2.sh that will use iPipe to start the master.sh. This is the script that will perform all pass-2 actions. • The master.sh will: • Restore CommCenter and SprinBoard for next boot • Unpack the main payload.zip file • Setup the environment (extract basepack.zip to /bin2 and add to PATH) • In-order, for each payload, unpack the corresponding zip (if available), run the script and clean up for the script • Setup the leftover directory (sh, chmod, mv, unzip and reboot) • Clean up the temporary environment • Create the “PHONE2PC.MSG” message file with “DONE” • Reboot

Option File

The options.inc file will contain sh style settings that can be used to convey control information from the front-end running on the PC/Mac to the back-end running on the iPhone. A typical options.inc is:

DEBUG=0 JAILBREAK=1 ACTIVATE=1 UNLOCK=1 BL_DOWNGRADE=1

The options.inc file will be sourced both in pass-1 and in pass-2. It can have any sh variable that can be used to control the execution of the scripts.

Payloads

A payload is a package which does a specific job. Payloads can do many things to your iPhone, e.g. jailbreak, activate, unlock system tuning, issue fixing, etc. In iLiberty+, a payload consists of two parts:

   1. A payload script
   2. A payload archive

The payload script is vital, it’s a must for a payload, the archive is put Into the payload folder under the iLiberty+ application folder.

For most of the work, an archive is required. For example, to install the BSD Subsystem, you have to have the BSD_Subsystem.zip archive downloaded from its original site. However, in some cases, there’ll be no archive. For example, to fix some 3rd party application issues on 1.1.3, all you have to do is only to create a symbolic link, no need to create any file.

How Payloads Are Put On iPhone

When you have chosen some payloads to execute, iLiberty+ will pack them into a single ZIP archive and upload it to iPhone before ramdisk boot. In pass 2, the master script will extract the archive into user’s Media folder, after extraction, the Media folder has the following structure:

   --Media
       |
       +- do_payload.sh
       +- iLiberty_Signature
       +- payload/payload1.sh
       +- payload/payload1.zip
       +- payload/payload2.sh
       +- payload/payload2.zip
       .
       .
       .

The bin folder is a minimal set of utilities iLiberty+ requires. The do_payload.sh is the main script that calls each and every payload script. The iLiberty_Signature is a footprint to help script determine the payload location. Please remember the above structure, knowing the payload location and structure will help you writing your own payload.

Payload Script Naming Convention

The payload concept was designed to be used in an incremental way. Small payloads doing simple tasks are combined to perform a large and complex one. This provides greater flexibility as well as simplifies maintenance.

On most cases, payloads can be executed in any arbitrary order. But sometime the order is extremely important. For example, downgrading the bootloader needs to be performed before the unlock, or the unlock will be lost and the resulting baseband will be empty. Another example is a fix for a specific application, that needs to run after the application is installed.

The method used to ensure the execution order is based on the payload name. Payloads are executed in alphabetical order (concept borrowed from the Unix RC). The script name is not required to follow any rules. Normally payload scripts should be prefixed by a 2-digit number (range from 00 to 99). Because some special payload needs to be run before others, we have used the following rules in our payloads:

• 00 to 09 for important payloads that normally require some privileges, activation, unlock, etc important payloads all fall into this range. For example, activation is normally the first thing to do, so it’s called 00Activate. • 3rd party payloads are just add-ons to iPhone system software, so they have the lowest order, we would like to use 90 to 99 for them.

In order to make several payloads can be done in correct order, we have arranged some important payloads in this order:

   00 - activation
   00 - bootloader upgrade/downgrade
   01 - baseband fix
   01 - baseband reflash
   02 - unlock
   10 - patches

The above arrangement ensures when multiple payloads are checked, they can be executed in a reasonable manner. For example, suppose we want to downgrade our bootloader to 3.9, then unlock it with AnySIM. From the above order, we know the bootloader will be downgraded first, when it’s done, the unlock will follow, and it’s just the correct order. If we don’t follow the above order, i.e. the unlock comes before bootloader downgrade, then it’ll fail.

Of course you don’t have to follow the above rules, but knowing the rule is good, because it allows you to give a correct script name to your payload. Let’s say we have a very kewl payload and we want it to be the very first payload to execute, we can name it:

   000VeryKewlPayload.sh

And it will be first executed.

Payload Script Header

iLiberty+’s payload script must comply to some conventions in order to be detected by the iLiberty+ application executable. The script must contains a header that describes things like the payload name, the archive, etc. The script header is in the following format:

1. !/bin2/sh
3. Name: name of the payload
4. Pack: archive name (can be empty if there's no zip archive)
5. URL: link to download the archive (empty if there's no zip archive)
6. Desc: payload description line #1
7. description continues to line #2
8. the last line #3 – followed by an “empty” line

The first line indicates the shell the script uses, normally it’s /bin2/sh (not /bin/sh), but there’s no problem using others (e.g. /usr/bin/python as long as it’s installed). Other lines are pretty self-descriptive. If there’s no contents for a field, just leave the filed name there, like this:

# Pack:

There’s one thing needs to be mentioned, the Desc field must be the last field in header, it can contain multile lines, it ends in an blank link or an empty comment line. So all the following formats are correct:

   Example 1:

# Desc: This is a single line description

   Example 2:

1. Desc: This description contains 2 lines
2. and it ends with an empty comment

   Example 3:

1. Desc: This description ends with a blank line

We’ll see a real example, the following script header is from a bundled script from the setup package:

1. !/bin2/sh
3. Name: OpenSSH 4.6p1-2
4. Pack: openssh-4.6p1-2.zip
5. URL: http://ste-repo.natetrue.com:15842/iphone-apps/zips/openssh-4.6p1-2.zip
6. Desc: OpenSSH Package

From the header we know, the payload is named OpenSSH 4.6p1-2, it requires an archive pack named openssh-4.6p1-2.zip, the archive pack can be downloaded from http://ste-repo.natetrue.com:15842/iphone-apps/zips/openssh-4.6p1-2.zip.

Payload Script Body

Following the script header, the script body begins. This is the real script you would like to execute on iPhone, you may write it in any way you prefer, but there are some points need to be considered:

Minimal BSD Tool Set

A newly jailbroken/activated iPhone doesn’t have BSD Subsystem or Cydia installed. iLiberty+ has copied a very limited tool set onto phone. The utilities are packed in the BasePack.zip, when being extracted, they are put into the /bin2 folder. Here’s the list:

   chmod
   chown
   cp
   dd
   dirname
   grep
   igsm
   ls
   mkdir
   plutil
   reboot
   rm
   sleep
   tar
   unzip

You should avoid modifying BasePack.zip by yourself because any further update may change this file and wipe out your modifications. If you need some special utilities that have not included in the BasePack.zip, please include them into your payload archive, in a sub-folder /bin. As an example, please check an AnySIM_XXX.zip archive.

Do remember that  the Media folder is on a NOEXECUTE disk. Therefore any command needs to placed in /bin2 folder.  Use the following procedure to copy executables to /bin2:

cp –pf <filename> /bin2/ chmod +x /bin2/<filename>

At the end, master.sh will erase the whole /bin2 folder. So you do not need to worry about erasing the executable.

Also, never rely on the executable left by another payload. That can lead problems if the right combination of payloads are not user or if the order is changed.

Internal Functions

An internal function script named functions.inc is copied to /bin2. Your script should source it to get the basic environment setup correctly (e.g. PATH, DEBUG, etc). So the following line should be put at the very beginning of the script (after the header):

   . /bin2/functions.inc

After sourcing it, the following environment variables are set:

SIGNATURE a signature file PL payload folder name PL_DIR full path to payload folder AFC_DIR full path to user's media folder USER_DIR full path to user's home directory OPTIONS contains user selected options, mainly for master.sh DEBUG 1 = on which logs all output, sent from GUI DEBUG_DELAY time (in seconds) to delay for debug, sent from GUI DEBUG_LOG debug log file name

As well as any other variable in options.inc

Also, there’re some internal functions defined in the functions.inc:

   GetFirmwareVersion
   GetBasebandVersion
   GetBootloaderVersion

The functions return the result into the variable you defined while calling the function. Here’s an example:

   . /bin2/functions.inc

   GetFirmwareVersion var_fw_version
   if [ ${var_fw_version} != "1.1.3" ]; then
       echo "Error: not version 1.1.3"
       exit 1
   fi

   GetBasebandVersion var_bb_version
   if [ ${var_bb_version} != "04.03.13_G" ]; then
       echo "Error: not baseband 04.03.13"
       exit 1
   fi

   GetBootloaderVersion var_bl_version
   if [ ${var_bl_version} != "3.9_M3S2" ]; then
       echo "Error: not bootloader 3.9"
       exit 1
   fi

You script may call these internal functions in case your payload is for a specific firmware/baseband/bootloader version.

Examples

Here are some examples which may help you further understand the payload script.

Example 1: Activate 1.1.4

Activativation requires to patch /usr/lib/lockdownd, so the script to activate 1.1.4 is mainly replacing the old lockdownd with a patched one. First, the header, we have described it earlier, so we’ll just skip it:

1. !/bin2/sh
3. Name: Activate 1.1.4
4. Pack: Activate114.zip
5. URL: http://iLiberty.zjlotto.com/Payloads/Activate114.zip
6. Desc: Activate iPhone firmware 1.1.4 with a patched lockdownd.

Now the main script body, we first invoke the internal functions to examine the firmware version, if firmware version is not 1.1.4, we pause for a few seconds so that user can know what happens:

. /bin2/functions.inc

echo "Activating 1.1.4..."

GetFirmwareVersion fw_version

if [ ${fw_version} != "1.1.4" ]; then echo "Wrong firmware version: ${fw_version}"

   	sleep 5
   	exit 1

fi

When version check succeeds, we can now extract our patched lockdownd to replace the old one, we also added some error detection and permission fix to make it fail-safe:

unzip -q -o ${PL_DIR}/Activate114.zip -d /usr/libexec/ if [ $? -ne 0 ]; then sleep 10 fi chmod 555 /usr/libexec/lockdownd

Last, we remove our archive:

rm -f ${PL_DIR}/Activate114.zip

echo "Done"

Note: althoug master script will delete the entire payload folder, it’ll a good idea to clean up our own package before leaving, because if there’re many payloads to install, the payload folder may occupy quite some disk space.

Example 2: General Fix for 3rd Party Apps

This is an example about how to write a script-only payload. Notice, in script-only payload, the PACK and URL fields in script header must be left blank.

Since many 3rd party application issue can be solved by adding a symbolic link as below:

/usr/local/arm-apple-darwin/lib/libgcc_s.1.dylib -> /usr/lib/libgcc_s.1.dylib

We can make a simple payload to fix it for us:

1. !/bin2/sh
3. Name: General Fix for 3rd Party App Issues
4. Pack:
5. URL:
6. Desc: This tiny payload creates a symbolic link for ibgcc_s.1.dylib,
7. this dynamic library is required by most 3rd party application.

. /bin2/functions.inc

echo "Adding libgcc_s.1.dylib symbolic link..."

GetFirmwareVersion fw_ver if [ ${fw_ver} != "1.1.3" -a ${fw_ver} != "1.1.4" ]; then echo "Lower versions need no fix"

      sleep 5
      exit 0

fi

mkdir -p /usr/local/arm-apple-darwin/lib ln -s /usr/lib/libgcc_s.1.dylib /usr/local/arm-apple-darwin/lib/.