George Zhu’s BLOG

NOTICE: Contents subject to change.

UPDATE: Revised to include the new format for the latest iLiberty+ version.

NOTICE: New payload header is not compatible with old versions (prior 1.3.0) of iLiberty+. If you have made your own payloads for old version iLiberty+, you may have to change the header slightly to use it on new iLiberty+ version, but normally the script body doesn’t need to change.

With the release of iLiberty+ (Windows) and iLibertyX (OS X), iPhone hacking has become a really easy thing. With iLiberty+’s open structure, it’s pretty easy to implement customized functions into it. This article explains in detail the payload technique used in iLiberty+. NOTE: iLiberty+ and iLibertyX comply to the same payload calling conventions, so the payload written for iLiberty+ also works on iLibertyX.

What Is A Payload

A payload is a package which does a specific job. A payload 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 optional. Both the script and the archive pack (if there is) must be 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 Device

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
    |
    +- bin
    +- do_payload.sh
    +- iLiberty_Signature
    +- payload/payload1.sh
    +- payload/archive1.zip
    +- payload/payload2.sh
    +- payload/archive2.zip
    .
    .
    .

The bin folder contains a minimal set of utilities that iLiberty+ requires. The do_payload.sh is the main script that calls each and every payload script in alphabetical order. 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 write your own payload.

Payload Script Naming

The script name does not need to follow any rules. But since the scripts are called one by one in their alphebetical order, so normally payload scripts are 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 priviliges, 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.

On the other hand, 3rd party payloads are just add-ons to iPhone system softwares, so they have the lowerest 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, Baseband erase/reflash
01 - Bootloader upgrade/downgrade
02 - Unlock
10 - Patches
87 - Cydia
88 - Installer
89 - BSD
90 - 99 Apps

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. Similarly, if we want to let a script run last, then name it to:

99ZLastPayload.sh

This will make it the last payload to execute.

Payload Script Header

The new payload script header is not compatible with old versions of iLiberty+, so this section is devided into two parts.

New format (for iLiberty+ version 1.3.0 and later)

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:

#!/bin/sh
#
# Id:      similar to bundleIdentifier
# Name:    name of the payload
# Author:  author of payload
# Version: payload version
# Script:  link to payload script
# Pack:    link to payload archive (can be empty if there's no zip archive needed)
# URL:     link to author's site
# Desc:    payload description line #1, you may
#          seperate descriptions into several lines
#          without problem
#

The first line indicates the shell the script uses, normally it’s /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:
# Desc: This description contains 2 lines
#         and it ends with an empty comment
#

Example 3:
# Desc: This description ends with a blank line

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

#!/bin/sh
#
# Id:      com.zjlotto.iLiberty.Unlock
# Name:    Unlock 03.14.08_G - 04.04.05_G
# Author:  George Zhu
# Version: 1.1
# Script:  http://iLiberty.zjlotto.com/Payloads2/02Unlock.sh
# Pack:    http://iLiberty.zjlotto.com/Payloads2/AnySIM_Unlock_BL39.zip
# URL:     http://george.insideiphone.com/
# Desc:    This payload works on both bootloader 3.9 and 4.6, for bootloader
#          4.6 it will change baseband to 04.02.13_G after unlock.
#

The above is the unlock payload script header, you can see it’s pretty easy understand it.

Old format (for iLiberty+ version prior 1.3.0)

Old format is slightly simpler, it is in the following format:

#!/bin/sh
#
# Name: name of the payload
# Pack: archive name (can be empty if there's no zip archive needed)
# URL: link to download the archive (can be empty if there's no zip archive needed)
# Desc: payload description line #1
#       description continues to line #2
#       the last line #3
#

NOTICE: Due to the different meaning of Pack and URL in new and old versions of iLiberty+, the new payload is not compatible with old iLiberty+ versions.

A real example:

#!/bin/sh
#
# Name: OpenSSH 4.6p1-2
# Pack: openssh-4.6p1-2.zip
# URL:  http://ste-repo.natetrue.com:15842/iphone-apps/zips/openssh-4.6p1-2.zip
# 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 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 bin folder under user’s (mobile or root) Media 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.

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 (deprecated)
. $FUNCTIONS

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

There’re some internal functions defined in the functions.inc:

GetFirmwareVersion
Syntax: GetFirmwareVersion var_name

GetBasebandVersion
Syntax: GetBasebandVersion var_name default_version

GetBootloaderVersion
Syntax: GetBootloaderVersion var_name

GetEnvironment
Syntax: GetEnvironment hasBSD hasInstaller

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

. $FUNCTIONS

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

GetBasebandVersion var_bb_version DEFAULT_VALUE
if [ ${var_bb_version} = "DEFAULT_VALUE" ]; then
    echo "Error: unable to determine baseband version"
    exit 1
fi 

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

GetEnvironment hasBSD hasInstaller
if [ ${hasBSD} = "BSD" ]; then
    echo "Found BSD"
elif [ ${hasBSD} = "CYDIA" ]; then
    echo "Found Cydia"
else
    echo "No BSD/Cydia installed"
fi
if [ ${hasInstaller} = "INSTALLER" ]; then
    echo "Found Installer"
elif [ ${hasInstaller} = "CYDIA" ]; then
    echo "Found Cydia"
else
    echo "Installer not found"
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:

Script header for latest iLiberty+

#!/bin/sh
#
# Id:      com.zjlotto.iLiberty.Activate
# Name:    Activate 1.1.4
# Author:  George Zhu
# Version: 1.0
# Script:  http://iLiberty.zjlotto.com/Payloads2/00Activate114.sh
# Pack:    http://iLiberty.zjlotto.com/Payloads2/Activate114.zip
# URL:     http://george.insideiphone.com/
# Desc:    Activates iPhone firmware 1.1.4 with a patched lockdownd.
#

Script header for old iLiberty+ versions (prior 1.3.0)

#!/bin/sh
#
# Name: Activate 1.1.4
# Pack: Activate114.zip
# URL: http://iLiberty.zjlotto.com/Payloads/Activate114.zip
# 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:

. $FUNCTIONS
 
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: Although master script will clean up the entire payload folder at the end of execution, it’s 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 spaces.

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:

For latest iLiberty+ (version 1.3.0 and above)

#!/bin/sh
#
# Id: com.zjlotto.iLiberty.Fix3rdPartyApp
# Name: General Fix for 3rd Party App Issues
# Author: <author>
# Version: 1.0
# Script: http://link.to.your.site/30Fix3rdPartyApp.sh
# Pack:
# URL: http://link.to.your.site/
# Desc: This tiny payload creates a symbolic link for libgcc_s.1.dylib,
# this dynamic library is required by most 3rd party application.
 
. $FUNCTIONS
 
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/.

For old iLiberty+ versions (prior 1.3.0)

/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:

#!/bin/sh
#
# Name: General Fix for 3rd Party App Issues
# Pack:
# URL:
# Desc: This tiny payload creates a symbolic link for libgcc_s.1.dylib,
# this dynamic library is required by most 3rd party application.
 
. $FUNCTIONS
 
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/.

NOTE: If there’s anything missing or not clearly explained in the article, please let me know. Comments are welcome.