Need help with aah?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

zydeco
152 Stars 21 Forks GNU General Public License v2.0 157 Commits 0 Opened issues

Description

arm64 architecture handler

Services available

!
?

Need anything else?

Contributors list

# 113,962
C
Objecti...
catalys...
iOS
157 commits

aah

arm64 architecture handler.

It uses unicorn and libffi to run iOS arm64 binaries on x86_64 macOS, with varying degrees of success.

Most things will fail to launch because they need frameworks/symbols that aren't available on macOS.

Requirements

  • macOS 10.15

To run iOS apps, aah relies on the Mac Catalyst frameworks that are present on macOS 10.15.

Running the sample app

The sample app is based on UIKitCatalog from the Apple sample code, with an integrated capstone disassembler to inspect functions and methods.

  1. Build the
    TestApp
    target. This builds an arm64 iOS app (
    TestApp.app
    ), and makes a copy with the Mach-O header changed to be emulatable (
    TestApp-aah.app
    , in the same output directory).
  2. Edit the
    aah-TestApp
    scheme, select the
    TestApp-app.app
    executable by choosing “Other...” from the Executable drop-down menu (under Run > Info) and selecting it from the filesystem. Otherwise Xcode will complain that the target doesn't match the current platform.
  3. Run the
    aah-TestApp
    scheme.

Steps 1 and 2 are only necessary before the first run.

How it works

  1. The architecture field of the binary is changed so macOS will load it.
  2. libaah.dylib
    is inserted with
    DYLD_INSERT_LIBRARIES
    .
  3. Upon load, it will detect which loaded binaries should be emulated, by looking at the
    reserved
    field in the header.
  4. On emulated binaries, the executable sections are changed to be non-executable. This will cause an
    EXC_BAD_ACCESS
    exception when it's executed.
  5. A signal handler is set to catch those exceptions, and emulate the code with unicorn.
  6. An unicorn instance will be creatd on each thread if needed, with its address space mirroring the host, except for executable sections:
    1. Sections with arm64 code are marked as executable for unicorn.
    2. Native-executable sections (i.e. system libraries) are marked as non-executable for unicorn. This causes an exception when unicorn tries to execute them, which is used to return execution to the host.

Transitions between native and emulated code

Transitions between host and emulated execution is handled by

libffi
at function entry/exit points, and requires the function signature to be known. This is done by keeping a mapping of entry points and their signatures (see
cif.c
).

The file

SymbolTable.plist
contains the signatures for supported functions (using Objective-C type encoding), and it's added as a section to the
libaah.dylib
binary. The key
objc shims
is used by the
objc_msgSend
shim to call variadic methods. This file is added as a section to the
libaah.dylib
binary at build time.

When new entry points are found at runtime, they are added with

cif_cache_add
or
cif_cache_add_new
. This is used for Objective-C methods, pthreads, blocks and function pointers.

The format of the method signature determines how the call is handled:

  1. A plain method signature will call the function by translating the arguments between the registers and stack of the host and emulator. This is enough for most functions.
  2. $
    + shim name: A shim that will be called when emulated code calls the function. The shim is defined with the
    SHIMDEF
    macro, it receives an emulator context where it can access the registers, and can return
    SHIM_RETURN
    or an address to continue execution. Examples:
    • Variadic functions:
      printf
      or
      NSLog
      (see
      nslog.m
      ).
    • Overriding functions with custom behaviour:
      objc_msgSend
      ,
      setjmp
      .
  3. <
    + method signature +
    >
    + wrapper name: Defines wrapper(s) that will be called after and/or before the native function is called. The wrappers are defined with the
    WRAP_EMULATED_TO_NATIVE
    and
    WRAP_NATIVE_TO_EMULATED
    macros, and have arguments
    rvalue
    and
    avalues
    that work like those of
    ffi_call
    . See
    libdispatch.c
    for examples.

Preparing an app

You will need a thin non-encrypted arm64 app to start with.

Repackaging

Repackage with this modified version of marzipanify.

This will do the following:

  1. Repackage it as a macOS app.
  2. Rename some linked libraries to the ones in
    /System/iOSSupport
  3. Change the executable's architecture to x86_64.
  4. Flag the executable so it's detected by
    libaah
    to be emulated (
    0x456D400C
    in the
    reserved
    field of the header).
  5. Remove the
    MH_PIE
    flag (probably not be needed, but makes debugging easier).
  6. Replace the
    LC_VERSION_MIN_IPHONEOS
    load command with
    LC_BUILD_VERSION
    , or update
    LC_BUILD_VERSION
    .
  7. Resign the package.

Libraries

Most binaries won't launch because of missing libraries or symbols. optool might help:

  • weaken linked libraries and symbols
  • rename linked libraries

After modifying the binary, it will have to be resigned:

If a library is present on macOS but missing some symbols, it's possible to build a stub library with the missing symbols, and make it export all of the original library by adding

-Xlinker -reexport_library /path/to/original.dylib
to its linker flags.

For functions in a native library to be called from emulated code, they must have an entry in

SymbolTable.plist
, as an Objective-C method signature. This can be automated with the
msdecl
tool from CParser, how to do this is somewhat documented in
SymbolTable/make_symbol_table.sh
.

If the app links to libc++, package it with the arm64 version included in

lib/libc++em.dylib
, and rename the linked library:
optool rename /usr/lib/libc++.1.dylib @executable_path/../lib/libc++em.dylib --target /path/to/package.app/Contents/MacOS/executable

Running

Run the patched executable inserting

libaah.dylib
:
$ DYLD_INSERT_LIBRARIES=/path/to/libaah.dylib /path/to/executable

Environment Variables

Some useful environment variables recognised by

aah
:
  • PRINT_DISASSEMBLY=1
    will print disassembled instructions as they are executed by the emulator.
  • PRINT_REGS=1
    will print the registers after and before function calls, or before printing each executed instruction (when combined with
    PRINT_DISASSEMBLY
    ).

Debugging

To debug, you'll need a custom build of debugserver that doesn't catch

EXC_BAD_ACCESS
exceptions, as this prevents them from being caught as signals in libaah:
  1. Download the llvm source:

    $ git clone [email protected]:llvm/llvm-project.git
    
  2. Patch

    lldb/tools/debugserver/source/MacOSX/MachTask.mm
    :
    diff --git a/lldb/tools/debugserver/source/MacOSX/MachTask.mm b/lldb/tools/debugserver/source/MacOSX/MachTask.mm
    index 6aa4fb23754..6148b628119 100644
    --- a/lldb/tools/debugserver/source/MacOSX/MachTask.mm
    +++ b/lldb/tools/debugserver/source/MacOSX/MachTask.mm
    @@ -601,7 +601,7 @@ bool MachTask::StartExceptionThread(DNBError &err) {
    
    
     // Set the ability to get all exceptions on this port
     err = ::task_set_exception_ports(
    •    task, m_exc_port_info.mask, m_exception_port,
    •  task, m_exc_port_info.mask &amp; ~EXC_MASK_BAD_ACCESS, m_exception_port,
         EXCEPTION_DEFAULT | MACH_EXCEPTION_CODES, THREAD_STATE_NONE);
      if (DNBLogCheckLogBit(LOG_EXCEPTIONS) || err.Fail()) {
       err.LogThreaded("::task_set_exception_ports ( task = 0x%4.4x, "
  3. Build debugserver with Xcode and install to

    /Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Versions/A/Resources/debugserver
    . You might want to save a backup of your original debugserver.
  4. In the

    aah
    project, edit the
    aah
    scheme and choose an executable/app to debug.
  5. Make sure the environment variables include

    DYLD_INSERT_LIBRARIES
    with
    $(TARGET_BUILD_DIR)/libaah.dylib
    first.
  6. Build & run

  7. It will hit a

    SIGBUS
    when it first encounters code to emulate. To prevent it, run this in the lldb console:
  8. There is already a shared breakpoint in the project that does this in

    init_aah
    .
    (lldb) process handle --pass true --stop false --notify true SIGBUS
    (lldb) continue
    

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.