Compilers needed:
The toolchain at Linux on Cell BE-based Systems | BSC-CNS is needed. Cobra is compiled with ppu-gcc version 4.1.1. It is unknown if other versions will work.
Other toolchains are known not to work. Mainly, due to incompatibilities with cryptcode, and with the macros at lv2/include/patch.h, as well as with some asm code. Porting cobra to other toolchain would be a matter of transalitng those files to the new toolchain.
sdcc, to comopile the i8051 binaries. Version 2.8.0 is used. It is unknown if a different version will cause any problem.
sony sdk, to compile netiso and cobralib. Any version is supossed to work.
gcc: (linux, mingw32, cygwin, etc), to compile the pc tools. these tools usually assume a little endian system like x86/x86_64
Overview of directories.
+ cryptcode
----+ include: include files with macros to encrypt functions
----+ src: the source code to decrypt functions (ps3)
----+ tool: the tool to encrypt the functions (pc)
cryptcode is a tool to encrypt functions with the purpose of obfuscate things a bit.
Additionally, it has the "suicidal" feature, which makes a function code to be destroyed after returning,
which is intended to be used on initialization functions that are not further used.
+ debug
----+ include
----+ src
Debug files to printf over lan. It also has patches to redirect kernel printf and the ttyWrite syscall to the library.
Debug library also works in ps2 emulator mode.
The files here are intended for debug phase only, and they are not linked when DEBUG is not defined.
+ lv1
----+ include
----+ src
Files for hypercalls and lv1 related functionality.
+ lv2
----+ include
----+ src
The lv2 kernel cobra "sdk".
It contains the defintions of a bunch of lv2 kernel functions for all kind of functionality (io, memory, processes, threads, modules, synchronization, etc).
The file symbols.h has the addresses of the functions. Some symbols have only been resolved for 3.55.
+ lv2gen
Tool to merge stage0 and stage1 with lv2 kernel.
To compile stage1, original encrypted lv2_kernel.self of 3.55 must be placed in this directory.
This tool requires failoverflow tools to be installed and be on the path.
+ stage0_file
Stage 0 of cobra, merged along with stage1 inside lv2_kernel.self.
It just changes the protection of lv2 kernel memory and then jump to stage1 (0x7f0000).
+ stage1_file
Stage 1 of cobra, it loads and decrypts stage 1.5 from cobra.
The current code is a bit difficult to understand, but it is basically a very simple virtual machine
with 4 opcodes and some obfuscation, that receives the opcodes from cobra usb. Operations end in a xor with a table.
The small vm code does stage 1 integrity via the md5 functions of lv2 kernel, and it also checks that some functions of the kernel are untouched.
It is intended as a first barrier against attackers, more protections are in stage 1.5.
Because of its "exotic" way of working, any code change or compiler change will break the code, it was not intended to be modified.
+ stage1.5
---+ gen: pc tool to generate the modified i8051 rom.
It modifies the opcodes of the given i8051 program. In addition, each data of each opcode is also xored with different values.
Furthermore, the full ROM is xored again with keys that are residual data from stage 1.
----+ loader: the i8051 program, must be compiled with sdcc. It checks that lv2 kernel, stage0 and stage1 haven't been modified, it does some handshake with the device to
check cobra usb authenticity, and it decrypts stage2, which is inside stage 1.5. It also self-checks stage 1.5 against modification.
----+ vm: the vm that implements a simple i8051 emulator. The opcodes and obfuscation xor values are autogenerated by the gen tool in opcodes.c file.
Currently, generation of stage 1.5 requires to modify some vars in the Makefile, this was intended to be automatic in the future by the stage1.5_gen tool.
----+ stage1.5_gen: it generates the encrypted stage1.5 file, that can be directly flashed on the device.
Stage 1.5 protection mechanism includes some additional operations ("side effects") done in the md5 functions (vm) to complicate reverse engeneering,
emulation and debugging techniques such as hooks.
Most attackers would assume that it is just a md5 function after seeing some constants, and they would stop the reverse of the function.
This protects against both: emulation where the attacker blindly implemented the md5 function, and some hooks where the attacker would hook the function:
calling original function, returning to his code and giving the proper value of the md5 without realizing that the state of the vm (instrCount) has been
modified with the data passed.
+ stage1.5_lan
An unprotected implementation of stage1.5 that loads decrypted stage2 from lan. Useful for debugging: flash stage1.5_lan to the device and you can send
stage2.bin with graf chokolo "sendfile" tool upon ps3 boot.
+ stage2
Cobra core itself. It implements almost all functionality of cobra (except ps2 and network isos). Its functionality is made available to the gui program (manager)
via syscall8 with subopcodes. (see syscall8.h). Every pointer in these syscalls is reduced to 32 bits (get_secure_user_ptr function) for security purposes.
----+ storage_ext.c: it implements the disc emulation system, providing functions to mount/umount disc files, and to send insert/eject events to devices.
In 5.0, a "proxy system" was added, so that the actual read could happen in user mode via ports/queues.
This is currently only used for the network iso features, where the network code is done by an user mode sprx loaded at the vsh process by the gui program.
----+ modules_patch.c: it contains the patches to user modules. It also implements some syscalls, so that the gui program can load a sprx in the vsh process to have resident code.
This is currently used only for network iso, but it could be used in the future to implemented "plugin" features, like resident ftp or something.
Due to security concerns, all modules of the firmware are currently hashed, this is to avoid the gui program and the netiso sprx to be easily dumped,
although that wouldn't be critical anyways.
----+ psp.c: it implements the reading of psp isos. See modulespatch.c for patches. Currently 3.55 and 4.00 psp emulator are supported. The gui program is able to mount
an encrypted fat32 image with the sys_storage_ext_mount_encrypted_image (storage_ext.c)
This is currently used to hide the 4.00 ofw emulator (which is further encrypted with our own sprx encryption), which is located in the "lambda.db" file in the
psp launcher package. Other than that and having a way of starting the psp emulator, the psp launcher doesn't have any function, the rest of the content is
filled with random fake data and black png images.
Currently mode 1 = 3.55 emulator, mode 2 = 4.00 emulator. The gui program determines which emulator to use by either user selection of mode,
or by a fixed list if mode is auto. (see cobralib).
+ stage2_cipher
PC tool to cipher stage2.
+ ps2emu
---- + include
---- + src
The ps2emu cobra "sdk".
It contains the defintions of some ps2emu functions.
The functionality is quite limited compared to the lv2 one, but there are still functions for file access (internal hdd only), libc, etc
The symbols.h contains the addresses of the functions.
Either PS2HWEMU, PS2GXEMU or PS2SOFTEMU must be defined to select between the "almost full hardware" emulator (CECHA, CECHB),
the gx emulator (CECHC, CECHE) and the software emulator.
+ ps2emu_gen
Tool to merge ps2emu stage1 with a ps2emu. Original 3.55 ps2_emu.self, ps2_gxemu.self and ps2_softemu.self must be placed in this directory to compile ps2emu stage1.
+ ps2emu_stage1_file
Stage1 for ps2emu, which is merged with emulators .self. It loads an encrypted ps2emu stage 1.5 from internal hdd, that previously cobra core wrote to a temporary file.
Compile with "make -f Makefile.hwemu", "make -f Makefile.softemu" and "make -f Makefile.gxemu" to select each emulator.
For the encryption, modification date of the file is used the key as well as very minor obfuscation to hide file name, further protection is done in ps2emu stage 1.5.
A different key is used for each emulator.
+ ps2emu_stage1_file_debug
Same as above but without protection, intended for debuggin purposes. It loads directly a decrypted ps2emu stage 2 skipping stage 1.5.
PS2EMU_DEBUG must be set in cobra core (lv2 stage2).
+ ps2emu_stage1.5
----+ gen: pc tool to generate the rom of i8051 program with modified opcodes, encryption, etc. Pretty much like its lv2 counterpart, except that it takes two i8051 programs
as arguments.
----+ preloader: first i8051 program. It sets the keys of the second i8051 program using predictable rand function from sdcc, and reboots the virtual machine at the addresses
of the second program.
----+ loader: second and main i8051 program. Decrypts and loads stage2. Some protection to avoid modification of ps2emu as well as self-modification is done.
Some protection is done using unused part of the ps2 emu arguments that were set by lv2. See lv2 stage2.
----+ xtea: small ppc program with xtea algorithm. It is to be used by loader.
----+ xtea_cipher: pc progra, it encrypts the xtea binary with lightweight encryption that can be handled by virtual program, and converts it into an array suitable for sdcc.
----+ vm: the vm that emulates a modified i8051 machine. Pretty much like its lv2 counterpart, with some slight differences.
----+ stage1.5_cipher: it ciphers the ps2emu stage 1.5, making it ready to flash to cobra usb.
+ ps2emu_stage2
The core of the ps2emu code. It handles the disc emulation in the ps2 lpar.
----+ common: the part of the implementation that is common to the 3 emulators. Disc emulation itself is really here. Also, code to read non original ps2 dvd is here.
PS2 emulator tipically read most dvd sectors by using a 2064 bytes raw read using an unofficial/undocumented/propietary scsi command.
However, this command only works for original discs, and there doesn't seem to be any way to bypass this from the ps3 software side.
The workaround to make DVD+-R to work is implementing the 2064 command by reading 2048 bytes from disc and faking the rest of data,
just like it is done for isos anyways.
----+ hwemu: the part of the implementation that is specific of ps2_emu.self
----+ gxemu: the part of the implementation that is specific to ps2_gxemu.self
----+ softemu: the part of the implementation thati s specific to ps2_softemu.self. Very similar to the gxemu one.
----+ stage2_cipher: pc tool to cipher ps2emu stage2.
+ netiso: user sprx with the implementation of network isos. This sprx uses the sys_storage_ext_mount_discfile_proxy function to get the disc read requests from kernel.
This sprx is loaded by the gui program in the vsh process space. Because of the special way in which is loaded, the start and stop routines must follow some rules:
start routine can't use some functions and it must end with a thread exit using directly the lv2 syscall and not the library function.
Same goes the stop function, but additionally, the stop function must finalize the module by itself.
+ ps3netsrv: pc aplication with the server code for network isos.
+ sprx_cipher2: tool to encrypt self/sprx for cobra usage only. Keys for gui (manager), vsh plugins (netiso) and 4.00+ psp emulator are different.
+ encrypt_image: it encrypts a fat32 image. Used currently to hide 4.00 psp emulator.
+ cobralib
The library given to the gui programmer. It encapsulates the syscalls to make things a bit easier to understand. It also does some processing, like psp keys setting,
and discless jailberak game setting.
For example, discless games in jailbreak format are implemented like this: an empty dummy ps3 iso is created by cobralib and mounted. After that, the jailbreak
game is mounted with the standard path redirection method. This approach allows to have disc command emulation at the same time that the standard path redirection, allowing
a near 100% discless compatibility.
+ usb
----+ cobramakefirm5.0: tool to create a cba file. The 5.0 directory includes the files that were used to generate cobra 5.0 firmware.
To generate a new firmware, replace the content of that folder with new stages 1.5, leave mcu.bin and other files, and use
"cobramakefirm 1 5.0 newfirm.cba"
----+ cobraflash: the flasher that is distributed to users.
+ cobrausbupdater: the ps3 version of cobraflash. Why are there idiots that try to reverse this when they have a pc version easier to reverse is unknown,
but this application is unprotected because there is anything too useful for attackers there.