node-applesign
===============

NodeJS module and commandline utility for re-signing iOS applications (IPA files).

Author
------

Sergi Alvarez Capilla aka pancake @ nowsecure.com

Program Dependencies
--------------------

* zip          - re-create IPA
* unzip        - decompress IPA (see `npm run unzip-lzfse`)
* codesign     - sign and verify binary with new entitlements and identity
* security     - get entitlements from mobileprovision
* insert_dylib - only if you want to use the -I,--insert flag

Usage
-----

When running without arguments we get a short help message

```
$ bin/applesign.js
Usage:

  applesign [--options ...] [target.ipa | Payload/Target.app]

  -a, --all                     Resign all binaries, even it unrelated to the app
  -b, --bundleid [BUNDLEID]     Change the bundleid when repackaging
  -c, --clone-entitlements      Clone the entitlements from the provisioning to the bin
  -f, --force-family            Force UIDeviceFamily in Info.plist to be iPhone
  -h, --help                    Show verbose help message
  -H, --allow-http              Add NSAppTransportSecurity.NSAllowsArbitraryLoads in plist
  -i, --identity [1C4D1A..]     Specify hash-id of the identity to use
  -L, --identities              List local codesign identities
  -m, --mobileprovision [FILE]  Specify the mobileprovision file to use
  -o, --output [APP.IPA]        Path to the output IPA filename
  -O, --osversion 9.0           Force specific OSVersion if any in Info.plist
  -p, --without-plugins         Remove plugins (excluding XCTests) from the resigned IPA
  -w, --without-watchapp        Remove the WatchApp from the IPA before resigning
  -x, --without-xctests         Remove the XCTests from the resigned IPA

Example:

  $ applesign -w -c -m embedded.mobileprovision target.ipa
```

The full help is displayed when passing the `--help` flag.

```
$ bin/applesign.js --help
Usage:

  applesign [--options ...] [input-ipafile]

  Packaging:
  -7, --use-7zip                Use 7zip instead of unzip
  -A, --all-dirs                Archive all directories, not just Payload/
  -I, --insert [frida.dylib]    Insert a dynamic library to the main executable
  -l, --lipo [arm64|armv7]      Lipo -thin all bins inside the IPA for the given architecture
  -n, --noclean                 keep temporary files when signing error happens
  -o, --output [APP.IPA]        Path to the output IPA filename
  -P, --parallel                Run layered signing dependencies in parallel (EXPERIMENTAL)
  -r, --replace                 Replace the input IPA file with the resigned one
  -u, --unfair                  Resign encrypted applications
  -z, --ignore-zip-errors       Ignore unzip/7z uncompressing errors

  Stripping:
  -p, --without-plugins         Remove plugins (excluding XCTests) from the resigned IPA
  -w, --without-watchapp        Remove the WatchApp from the IPA before resigning
  -x, --without-xctests         Remove the XCTests from the resigned IPA

  Signing:
      --use-openssl             Use OpenSSL cms instead of Apple's security tool
  -a, --all                     Resign all binaries, even it unrelated to the app
  -i, --identity [1C4D1A..]     Specify hash-id of the identity to use
  -k, --keychain [KEYCHAIN]     Specify alternative keychain file
  -K, --add-access-group [NAME] Add $(TeamIdentifier).NAME to keychain-access-groups
  -L, --identities              List local codesign identities
  -m, --mobileprovision [FILE]  Specify the mobileprovision file to use
  -s, --single                  Sign a single file instead of an IPA
  -S, --self-sign-provision     Self-sign mobile provisioning (EXPERIMENTAL)
  -v, --verify                  Verify all the signed files at the end
  -V, --verify-twice            Verify after signing every file and at the end

  Info.plist
  -b, --bundleid [BUNDLEID]     Change the bundleid when repackaging
  -B, --bundleid-access-group   Add $(TeamIdentifier).bundleid to keychain-access-groups
  -f, --force-family            Force UIDeviceFamily in Info.plist to be iPhone
  -H, --allow-http              Add NSAppTransportSecurity.NSAllowsArbitraryLoads in plist
  -O, --osversion 9.0           Force specific OSVersion if any in Info.plist

  Entitlements:
  -c, --clone-entitlements      Clone the entitlements from the provisioning to the bin
  -e, --entitlements [ENTITL]   Specify entitlements file (EXPERIMENTAL)
  -E, --entry-entitlement       Use generic entitlement (EXPERIMENTAL)
  -M, --massage-entitlements    Massage entitlements to remove privileged ones
  -t, --without-get-task-allow  Do not set the get-task-allow entitlement (EXPERIMENTAL)
  -C, --no-entitlements-file    Do not create .entitlements file in the IPA

  -h, --help                    Show this help message
      --version                 Show applesign version
  [input-ipafile]               Path to the IPA file to resign

Examples:

  $ applesign -L # enumerate codesign identities, grab one and use it with -i
  $ applesign -m embedded.mobileprovision target.ipa
  $ applesign -i AD71EB42BC289A2B9FD3C2D5C9F02D923495A23C target.ipa
  $ applesign -m a.mobileprovision -c --lipo arm64 -w target.ipa

Installing in the device:

  $ ideviceinstaller -i target-resigned.ipa
  $ ios-deploy -b  target-resigned.ipa

```

List local codesign identities:

	$ bin/applesign -L

Resign an IPA with a specific identity:

	$ bin/applesign -i 1C4D1A442A623A91E6656F74D170A711CB1D257A foo.ipa

Change bundleid:

	$ bin/applesign -b org.nowsecure.testapp path/to/ipa

Signing methods
---------------

There are different ways to sign an IPA file with applesign for experimental reasons.

You may want to check the following options:

**-c, --clone-entitlements**

put the entitlements embedded inside the signed mobileprovisioning file provided by the user as the default ones to sign all the binaries

**-S, --self-sign-provision**

creates a custom mobileprovisioning (unsigned for now). installd complains

**-E, --entry-entitlement**

use the default entitlements plist. useful when troubleshooting

The default signing method does as follow:

* Grab entitlements from binary
* Remove problematic entitlements
* Grab entitlements from the provisioning
* Adjust application-id and team-id of the binary with the provisioning ones
* Copy the original mobileprovisioning inside the IPA
* Creates ${AppName}.entitlements and signs all the mach0s

After some testing we will probably go for having -c or -E as default.

In addition, for performance reasons, applesign supports -p for parallel signing. The order of signing the binaries inside an IPA matters, so applesign creates a dependency list of all the bins and signs them in order. The parallel signing aims to run in parallel as much tasks as possible without breaking the dependency list.

Mangling
--------

It is possible with `--force-family` to remove the UISupportedDevices from the Info.plist and replace the entitlement information found in the mobileprovisioning and then carefully massage the rest of entitlements to drop the privileged ones (`--massage-entitlements`).

Other interesting manipulations that can be done in the IPA are:

**-I, --insert [frida.dylib]**

Allows to insert a dynamic library in the main executable. This is how Frida can be injected to introspect iOS applications without jailbreak.

**-l, --lipo [arm64|armv7]**

Thinifies an IPA by removing all fatmach0s to only contain binaries for one specified architecture. Also this is helpful to identify non-arm binaries embedded inside IPA that can be leaked from development or pre-production environments.

In order to thinify the final IPA even more, applesign allows to drop the watchapp extensions which would not be necessary for non Apple Watch users.

Performance
-----------

Sometimes the time required to run the codesigning step matters, so applesign allows to skip some steps and speedup the process.

See `--dont-verify` and `--parallel` commandline flags.

Enabling those options can result on a 35% speedup on ~60MB IPAs.

API usage
---------

Here's a simple program that resigns an IPA:

```js
const Applesign = require('applesign');

const as = new Applesign({
  identity: '81A24300FE2A8EAA99A9601FDA3EA811CD80526A',
  mobileprovision: '/path/to/dev.mobileprovision',
  withoutWatchapp: true
});
as.events.on('warning', (msg) => {
  console.log('WARNING', msg);
})
.on('message', (msg) => {
  console.log('msg', msg);
});

as.signIPA('/path/to/app.ipa')
.then(_ => {
  console.log('ios-deploy -b', as.config.outfile);
})
.catch(e => {
  console.error(e);
  process.exitCode = 1;
});

```

To list the developer identities available in the system:

```js
try {
  const ids = await as.getIdentities();
  ids.forEach((id) => {
    console.log(id.hash, id.name);
  });
} catch (err) {
  console.error(err, ids);
}
```

Bear in mind that the Applesign object can tuned to use different
configuration options:

```js
const options = {
  file: '/path/to/app.ipa',
  outfile: '/path/to/app-resigned.ipa',
  entitlement: '/path/to/entitlement',
  bundleid: 'app.company.bundleid',
  identity: 'hash id of the developer',
  mobileprovision: '/path/to/mobileprovision file',
  ignoreVerificationErrors: true,
  withoutWatchapp: true
};
```

Further reading
---------------

See the Wiki: https://github.com/nowsecure/node-applesign/wiki

* https://github.com/maciekish/iReSign
* https://github.com/saucelabs/isign
* https://github.com/phonegap/ios-deploy

Pre iOS9 devices will require a developer account:

* http://dev.mlsdigital.net/posts/how-to-resign-an-ios-app-from-external-developers/