Revision as of 15:56, 25 August 2014

Welcome to the wonderful world of 3DS Homebrew!

To run homebrew on your 3DS you need a method to run custom code. There is currently only one public exploit (the MSET exploit) available which allows running unsigned code on a 3DS system. A 3DS running on System Software version 4.1.x to 4.5.x is required for this exploit, but Smealum is working on a new vulnerability found on 3DS System Software version 4.x to 8.x.

The different exploits

The MSET exploit

This exploit only works on 3DS System Software version 4.1.x to 4.5.x

This exploit is also used by Flashcart manufacturers to take over the 3DS's kernel.

This is currently the only method to run homebrew.

To exploit this vulnerability, you need a working DS Mode flashcart for your 3DS and you must run an NDS Homebrew designed to alter the DS Profile settings strings. When launching the 3DS System Settings application's DS profile settings editor, it will cause the application that edits the DS profile to crash, and this crash pushes custom code into memory from within the edited profile and makes the security co-processor "accidentally" load that code, resulting in homebrew being launched.

Go to the MSET exploit page, or on this blog to read more information on the hack itself.

SSSpwn Exploit (Name may not be final)

Unreleased.

Smealum uses this exploit for his homebrew launcher. It works on 3DS System Software version 4.x to 8.x at the time of writing. It is planned to be usable from 3DS System Software version 4.x to the newest available 3DS System Software version at the time of release.

The executable formats

There are a few different types of executables made for the 3DS at this time.

The .cxi format

This file format is used officially by the console. The .cxi container type can only be launched on a 3DS Development Unit (A 3DS released to developers).

This is not a format used by the homebrew community. It's listed for historical reasons.

The .bin format

This type is the raw format for homebrew compiled into an ARM binary file. It's usually encapsulated into a Launcher.dat file to be launched using the MSET exploit, or converted into a .3ds file to be launched using a front-end homebrew launcher.

• Boot method: Encapsulated into a Launcher.dat, or using a .bin launcher homebrew.
• Filename: Whatever you want, with a .bin extension
• Requirement: Python to encapsulate it into a Launcher.dat file, or a method to launch .bin homebrew on your console.
• Access level: Same as Launcher.dat (Full Kernel-mode control).
• Restriction: When running from a broken-kernel state (Launcher.dat direct from MSET), random regions of the RAM are likely to have the NX (No-eXecute) security bit still active on them. This causes the program to sometimes not be able to start as the memory is set to not allow execution from the address range the program was unluckily loaded into. This also limits the size of the application, as when the application is larger, the chance of it landing in NX-enabled regions is significantly larger than if it is smaller, leaving the likeliness of it being able to start, up to luck.

If you get homebrew in this format, you will need a python script to insert it into a Launcher.dat file.

• 3DS Python Tool by Naehrwert.
• Build.py for Linux by Tomiga.
• build.py by Kane49. (Advice from here: make sure to change both instances of "-mcpu=mpcore -march=armv6k" in it to "-mcpu=arm946e-s -march=armv5te")

Or use a script to copy a ROP header and footer around the payload binary file, example: copy /b header+binary+footer Launcher.dat

You can find the pre-compiled ROP header (exp.bin) and footer (pad.bin) in Snailface's 3DS Homebrew demo package.

The Launcher.dat format

• Boot method: The homebrew is launched directly from the MSET exploit.
• Filename: The homebrew filename is always "Launcher.dat", as that is the expected string hard-coded into the MSET exploit's publicly available ROP chains, so you can't have multiple homebrew at the same time on your console.
• Requirement: You need a DS flashcart to install the MSET vulnerability and run the Launcher.dat homebrew.
• Access level: The homebrew has full Kernel-mode access and has access to both the ARM9 and ARM11 cores, but the console's services in ARM11 are all disabled, due to the public method of taking over the ARM11 core from within the ARM9 core (credit to Kane49) (This means you have no access to the 3D slider, sound, etc. unless you code it back yourself).
• Restriction: file size (same as .bin homebrew)

The .3ds format

• Boot method: The homebrew is launched from a front end launcher.
• Filename: The homebrew filename can be what you want and ends with .3ds extension.
• Requirement: There is currently only one front end, which is based on the work done by Smealum to create a homebrew environment, and requires a Gateway 3DS flashcart running firmware 2.2 OMEGA or newer.
• Access level: The homebrew is only allowed User-mode access and has access to only 30% of the system core's first CPU thread, and 100% access to the second thread. As a result, the homebrew cannot modify or access the system in any way using the current implementation of ARM11 homebrew, but the ARM11 services are available.

Launching Homebrew

ATTENTION: All homebrew using a Launcher.dat file have full Kernel access and therefore can modify the content of your console. Nobody developed or released homebrew explicitly bricking your 3DS, but be careful when you decide to run unknown files. You are responsible for any problem you may encounter.

The Launcher.dat format

This exploit works by using a ROP (Return-Oriented Programming) Chain to get access to Kernel-mode control and run a homebrew executable.

There are two ROP chain exploits you can use:

• Gateway 3DS's ROP Chain. (Encrypted ROP Chain)
• Fierce Waffle's Open source ROP chain. (Unencrypted ROP Chain)

The Launcher.dat file contains two sections: The end of the ROP chain initiated by the MSET exploit, and the homebrew binary.

Gateway 3DS, which was the first to publicly release this exploit, encrypted their ROP chain to prevent flashcart clones. If you install the Gateway ROP chain, you will have to encrypt your Launcher.dat homebrew using their encryption key. If you install an open source ROP chain, you can run unencrypted homebrew, but you will not be able to run Gateway 3DS's Launcher.dat until you reinstall their own ROP chain.

There are tools to quickly encrypt or decrypt a Launcher.dat file to work with a corresponding ROP chain.

The different ROP Chain installers

• Gateway 3DS ROP chain installer. (No link will be shared here. The installer is provided with the Gateway-3DS flashcart firmware package.)
• ROP Chain installer, by Fierce Waffle. It's a little unstable and can brick the DS Mode of the console. It requires a full 3DS format to fix it. You will lose all your data installed on 3DS if you format it.
• Alternate ROP Installer, by Drenn, based on Fierce Waffle ROP Chain binary. It's restoring a full NVRAM dump of Drenn's DS Profile to your console. More stable than using the real installer, but it will fully replace your profile information, except your WiFi settings. You can use ROP Installer Modifier to edit the DS profile information (Favorite color and user name) to be written to the profile during the installation.
• ROP MultiLoader, by SnailFace. Lets you easily choose the ROP chain you want to install.

Installing a ROP Chain

The ROP chain installation requires a DS-mode Flashcart to run the installer .nds program.

1. Choose a ROP chain installer from the list above.
2. Extract the NDS file if needed and place it on your MicroSD Card, then insert it into your compatible NDS-mode Flashcart.
3. Insert the NDS-mode flashcart into your 3DS console and launch the installer.

Note: If you launch the DS-mode again (DS Game or DS mode Flashcart) after installing the ROP Chain, the profile will be reset and the exploit deleted. You will need to install it again to launch 3DS homebrew.

Launching the Homebrew

1. Encrypt or Decrypt the Launcher.dat file based on the ROP chain you installed. (Gateway ROP chain requires encryption)
2. Place the Launcher.dat file on the root of your SD Card.
3. Boot the 3DS and go to Settings > Other > Profile > DS Profile.
4. The homebrew will launch.

The .3ds format

The .3ds homebrew use ctrulib libraries instead of being developed on bare ARM commands.

The .3ds format requires a front end to be launched first. There are actually two front ends you can use currently.

Gateway 3DS Flashcart

This Front end require the Gateway 3DS Flashcart and the Omega 2.2+ firmware only. It's launched using the Launcher.dat exploit and thus works only on 3DS System version 4.0 to 4.5.

1. Install the Gateway 3DS ROP Chain.
2. Place the Gateway 2.2 Omega Launcher.dat file on the root of your SD Card.
3. Place your homebrew on your MicroSD Card formated as FAT32 or ExFAT, using the filename you want and .3ds extension.
4. Launch Gateway from the DS Profile and update your card's firmware if required.
5. Press Select button to list all homebrew on your MicroSD card and press A to mount it.
6. Launch it like a game.

The 3DS Homebrew Launcher

The 3DS Homebrew Launcher lets the user run unsigned homebrew compiled in .3ds format, with the same User-mode permissions as the Gateway loader. It's being developed by Smealum and gemisisDev, and is planned to exploit a vulnerability in 3DS System Software versions 4.x to 8.x, found by Smealum, to run homebrew in User-mode on the ARM11 core.

You will not need a Flashcart to use it.

As the exploit and loader are yet to be released, the launching method is yet to be know.

Developing homebrew for 3DS

If you have any questions, you can come to GBATemp's main homebrew development and help thread. It contains shared sources, examples and libraries.

You can find all known resources (hardware registers, syscalls, utilities) to develop your homebrew on http://3dbrew.org.

To develop 3DS homebrew you need a development environment consisting of tools, scripts and libraries which will be detailed below. The languages used to write homebrew is C, C++ and ASM, then the sources are compiled to binary using GNU GCC-ARM and Devkit pro with DevkitARM. It will also require Python if you plan to create ARM9 homebrew (Launcher.dat format). The available tools and SDK work on Windows 32/64bit and Linux.

Development environment

ARM9 and ARM11 setup

detail here, or link if it's too long.

ARM11 additional setup

detail here, or link if it's too long.

Writing your first code

Maybe link to a different page starting from here.

Make a hello world example from scratch.

Compiling

same here

ARM9

ARM11

Releasing

Please create (and maintain) a page on this Wiki and/or 3dbrew about your homebrew. It will help referencing it, and will be easier for everyone to find if there's any update and follow your homebrew progress, sources and links.