PORTING

   1 ================================================================================
   2                          Porting AsbestOS to a device
   3 ================================================================================
   4
   5 AsbestOS is designed to be easy to port to any implementation of the Lv-2 USB
   6 exploit (or, indeed, even future exploits). There are two main components
   7 in the distribution:
   8
   9 - stage1
  10 - stage2
  11
  12 Stage1 is the first code portion of AsbestOS that runs (it may be preceded by
  13 an "egghunt" exploit phase on some versions of the exploit, but that's up to the
  14 exploit). It installs a USB driver into Lv-2, then waits until the "final" USB
  15 device is connected. Once it is, it requests stage2 in chunks, then launches it.
  16 It is also responsible for initially catching both CPU threads.
  17
  18 Stage2 is the main portion of AsbestOS and is responsible for replacing Lv-2,
  19 cleaning up after it, setting up the initial network, and loading the kernel via
  20 TFTP. It is also compressed and wrapped with a decompressor stub.
  21
  22 AsbestOS has very few requirements, making it very easy to port to existing
  23 implementations of the USB exploit, whether on microcontroller dongles, portable
  24 media players, phones, etc. The only requirements are:
  25
  26 - At least 40KB of free internal or external storage (currently),
  27 - Implementation of a few USB control messages to deliver stage2 on-demand,
  28 - An incarnation of the exploit able to execute at least a <3KB buffer of code
  29   (no requirements on location or input registers).
  30
  31 Your implementation must eventually load and direct execution to the code in
  32 stage1.bin. This code is position-independent (with some overlapping exceptions)
  33 and does not require any specific values for input arguments. It will return to
  34 the caller when done installing the device driver. If your implementation
  35 requires any headers before the payload (e.g. descriptors, metadata), keep those
  36 and simply replace the data where the executable code begins.
  37
  38 The device must eventually virtually insert a USB device with vendor ID 0xAAAA
  39 and Product ID 0x3713. At this stage, stage1 will issue the following USB
  40 control requests to it:
  41
  42 PRINT (bmRequestType=0x40, bRequest=1, wLength=len)
  43         Print a debug message. If you don't have any usable debug output, just
  44         accept and discard the data.
  45 GET_STAGE2_SIZE (bmRequestType=0xc0, bRequest=2, wLength=4)
  46         Get the total size of stage2. You should return 4 bytes indicating the size
  47         of stage2 in BIG-ENDIAN byte ordering.
  48 READ_STAGE2_BLOCK (bmRequestType=0xc0, bRequest=3, wIndex=offset, wLength=len)
  49         Return a block of stage2. The stage1 code issues reads in blocks of 0x1000
  50         bytes, except for the last block. wIndex is the offset in units of 0x1000
  51         bytes (that is, the offset >> 12).
  52
  53 For example, on a microcontroller with at least 64KB of Flash, you could build
  54 in stage2, while on a microcontroller with less Flash you could stream it from
  55 an external memory (EEPROM, Flash, SD card, ...) or even through a serial port
  56 from a PC.
  57
  58 In other words, on any device currently executing a PSJailbreak-derived payload,
  59 you just need to replace it with stage1, add in stage2, and add three request
  60 handlers to deliver stage2 when requested, and change the final device VID to
  61 0x3713.
  62
  63 If you believe that the current vanilla stage1 will not work for your device,
  64 please drop me a line and I'll try to accomodate for it. It's easier if I add
  65 a few configuration options and keep a common codebase instead of ending up with
  66 a dozen minor forks for device-specific tweaks. There shouldn't be much to
  67 change in stage1 anyway, except for possibly timing.
  68
  69 Licensing notes:
  70
  71 Stage1 and stage2 are licensed under the GNU General Public License, version 2.
  72 However, you can insert stage1/2 into any implementation of the exploit, which
  73 need not be licensed under the GPLv2. This is because simply embedding a binary
  74 blob isn't considered "linking" in any practical sense (even if you technically
  75 use the linker); it isn't any different from, say, embedding GPLv3 code inside
  76 an initramfs built into a GPLv2 Linux kernel. Any modifications that you make
  77 to the stage1 or stage2 code, must be licensed under the GPLv2. As usual,
  78 please make sure that you comply with all the licenses involved.