Difference between revisions of "3DS Homebrew"

Revision as of 02:55, 1 February 2015

Welcome to the wonderful world of 3DS Homebrew!

To run homebrew on your 3DS you need a method to run custom code. There are currently two public exploits available which allow running unsigned code on a 3DS system: The MSET exploit and Ninjhax.

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.

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 on this blog to read more information on the hack itself.

Ninjhax ("SSSpwn")

Released November 20th 2014

Ninjhax is an exploit developed by Smealum to launch homebrew. It is launched via the game Cubic Ninja.

It works on 3DS System Software version 4.x to 9.x at the time of writing.

Videos: Here it is in use.

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: 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: 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. The size limit is around 19-22kb. In ARM11, code is loaded in a clean memory area, but before jumping to ARM11 it starts in ARM9 and is loaded in the same location, so the problem could happen too.

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 usually "Launcher.dat" but can come using the "MsetForBoss.dat" variant using a alternate MSET exploit roploader, you can have upto 2 homebrew files at the same time on your console (one using the launcher.dat file name and one with the name MsetForBoss.dat), but it requires switch between DS profile roploaders to alternate which file will be loaded.
• Requirement: You need a DS flashcart to install the MSET vulnerability and run the Launcher.dat homebrew.
• Access level: Full Kernel-mode control (same as .bin homebrew).
• Restriction: file size (same as .bin homebrew)

There are 2 different formats of launcher.dat/MsetForBoss.dat, unencrypted(also referred to as homebrew or non gateway), and encrypted(also known as gateway encrypted) you will need to use a alternate DS profile exploit depending on whether you are trying to run a encrypted or unencrypted launcher.dat file, but most if not all MsetForBoss.dat files are unencrypted

The .3ds / .3dsx format

• Boot method: The homebrew is launched from a front end launcher.
• Filename: For Smealum's homebrew launcher use boot.3dsx, every homebrew has a different folder. Fir Gateway use any name .3ds and place in on a microSD.
• Requirement: For the gateway (.3ds) requires a Gateway 3DS flashcart running firmware 2.2 OMEGA or newer. For Smealum's homebrew launcher (.3dsx) requires Cubic Ninja and an SD card with boot.3dsx (can be either your homebrew or the homebrew launcher) files on it you'll also need a wifi connection to the internet from your 3DS.
• Access level: The homebrew ran using Smealum's homebrew launcher 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. Homebrew ran using the gateway will have as much access as any other game.

The .cia format

This file format is used officially by the console as a container for eShop downloaded contents. It's meant to be extracted, installed and displayed on the console's system menu using its own icon.

The .cia container type can only be installed on a 3DS with installation privilege. To unlock the installation feature, you need a modified EmuNAND or Gateway 3DS v2.6 or newer.

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 .cxi format

There's currently no method to launch this format on a retail unit.

The .bin/elf format

These formats are the raw executable.

Some ARM9 (in Launcher.dat format) experimental homebrew can launch the .bin format, but require a 3DS with a System Software version 4.x.

There's currently no .elf homebrew launcher to use with Ninjhax.

These files are usually converted to another format (dat, cia, 3ds, 3dsx) by the developers when released to public. Then can then be launched using one of the existing homebrew loading methods below.  

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 format requires a gateway 3DS flashcart or a MT-card flashcart.

Gateway 3DS Flashcart

The Gateway 3DS flashcart homebrew launcher can be used only on a 3DS System version 4.0 to 4.5. The flashcart is required as the 3DS homebrew are stored on the MicroSD inserted in the flashcart. This Homebrew launching method requires the Gateway 3DS firmware version 2.2 Omega or newer.

1. Install the Gateway 3DS ROP Chain. (See the ROP chain installation method above)
2. Place the Gateway Launcher.dat file on the root of your SD Card.
3. Place your homebrew on the root of your MicroSD Card formated as FAT32 or ExFAT, using the filename you want and .3ds extension.
4. Launch Gateway from the DS Profile.
5. Press Select button to list all homebrew on your MicroSD card and press A to mount it.
6. Launch it like a game.

MT-Card Flashcart

The MT-Card homebrew launcher can be used only on a 3DS System version 4.0 to 4.5. The flashcart is required as the 3DS homebrew are stored on the MicroSD inserted in the flashcart. This Homebrew launching method requires the MT-Card firmware version 2.0 or newer.

1. Install the MT-Card exploit using the DS mode flashcart. (See the ROP chain installation method above)
2. Place the MT-Card Launcher.dat file on the root of your SD Card.
3. Place your homebrew on the root of your MicroSD Card formated as FAT32 or ExFAT, using the filename you want and .3ds extension.
4. Launch MT-Card from the DS Profile.
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 .3dsx format

The .3dsx format requires a front end to be launched first.

The Homebrew Launcher

The Homebrew Launcher lets the user run unsigned homebrew compiled in .3dsx format in User-mode on the ARM11 core. It was originally developed by smealum and gemisisDev, since its release more developers are helping and improving it. It exploits a vulnerability in 3DS a System Software versions 4.x to 9.2.x with eShop revision 7 to 20.

You will not need a Flashcart to use it, but will need the retail game Cubic Ninja. Cubic Ninja launched from a flashcart is working too.

Installing The Homebrew Launcher

1. Download and extract The Homebrew Starter Kit to the root of your 3DS SD Card. You should now have a file named boot.3dsx and a "3ds" folder on the root of your SD Card.
2. Enable Wifi and launch Cubic Ninja game
3. Choose the "Create" menu and select "QR Code" method, then "Scan QR code" option.
4. Go to http://smealum.net/ninjhax/#qrcode and select your System version to generate the corresponding QR Code
5. Scan your QR code and it will download "The Homebrew Launcher" loader automatically and install it into the Savegame slot of Cubic Ninja game. It will also launch automatically after the Installation.

Launching The Homebrew Launcher

1. You don't need Wifi once it's already installed to your Cubic Ninja game.
2. Run Cubic Ninja and go to QR Code menu. The Homebrew Launcher will load.

Place your homebrew in either one of these locations:

1. /3ds/<homebrew_name>/boot.3dsx
2. /3ds/<homebrew_name>/<same_as_folder_name>.3dsx
3. /3ds/<filename>.3dsx

If you want an icon for your Homebrew to be displayed in The Homebrew Launcher, place it in either one of these locations:

1. /3ds/<homebrew_name>/icon.bin
2. /3ds/<homebrew_name>/<icon or folder_name>.smdh
3. /3ds/<homebrew_name>/<icon or folder_name>.icn

The .cia format

The .cia format requires a patched EmuNAND or Gateway 3DS flashcart. The user needs a 3DS with a System Software version 4.0.x to 4.5.x in the first case, or 4.0.x to 9.2.x in the second.

Dev Menu

Currently, one of the ways to install cia files and manage installed titles is by using DevMenu program from the official Nintendo 3DS development kit (SDK). This program is illegal to share and will not be linked here or on the forum. However, homebrew alternatives exist such as Big Red Menu. To use DevMenu and install files to your NAND or EmuNAND, you need enough privileges which is only possible on a modified EmuNAND (commonly called "custom Firmware") or using Gateway 3DS v2.6 or newer.

- When using a modified EmuNAND you need to permanently install DevMenu program on your console.

- when using Gateway 3DS you can use BigBlueMenu, which is the DevMenu program converted to .3ds format.

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 or Devkit pro with DevkitARM. Python can also be used to compile ARM9 homebrew (Launcher.dat format). The available tools and SDK work on Windows 32/64bit and Linux.

3dsx homebrew

Development environment

If you want to created homebrew in 3dsx format to be launched from Ninjhax exploit you will need to install DevkitPro with the 3DS User Library (CTRULib).

• Install DevkitPro + DevkitARM + CTRULib by following this guide if you are using Linux or Mac.
• If you are using Windows, use the automated-installer. Install in C:\devkitPro\ and it will install all the latest versions of the required programs (you can disable DevKit PSP, but be sure to enable CTRULib in DevkitARM menu). It will create the environment variables automatically.

Examples

You can find ctruLib homebrew examples here: https://github.com/smealum/ctrulib/tree/master/examples

To compile, open a command line window and browse to the homebrew folder and type make, or create a batch file in the same folder with the "make" command in it.

Launcher.dat and .3ds homebrew

If you don't need Kernel access, prefer developing homebrew in 3dsx format. Remember that the .dat format works only on 4.1.x-4.5.x consoles.

The guide to setup a 3ds homebrew environment is old and need to be rewritten.

Please rewrite a guide here.

Development environment

If you already installed Devkit ARM with CTRuLib, you don't need to follow the installations steps, unless you want to compile using Python instead of Makefile.

Install Python 2.7.x

Note: You can skip this step if you want. Go to step 2. directly if you don't want to use Python to compile your homebrew.

• Download the latest version of Python 2.7.x
• Install Python on your computer.
• If you are on Linux, add Python to your environment variable $PATH
• If you are on Windows, install it in C:\Python27\, and it should edit the environment variable "Path" automatically.

If you need to do it manually, follow these steps:

• Go to My Computer > Right-click > Properties > Advanced tab > Environment variables > System variables
• In the list search for "Path", select it and press Edit/Modify
• At the end of the line, add this:

;C:\Python27

It will allow you to call the Python program from any place by typing "Python" in a command line window.

Install a compiler

• Install DevkitPro + DevkitARM + CTRULib by following this guide if you are using Linux or Mac.
• If you are using Windows, use the automated-installer. Install in C:\devkitPro\ and it will install all the latest versions of the required programs (you can disable DevKit PSP, but be sure to enable CTRULib in DevkitARM menu). It will create the environment variables automatically.

You can install and use GNU Tools for ARM Embedded Processors as alternate compiler, but it will not be enough to develop ARM11 homebrew as you will need additional libraries provided by DevkitPro. If you use this compiler for ARM9 homebrew, you will also need to add the ARM binaries path to your environment variables. Follow the previous Python steps to add this path:

;C:\Program Files\GNU Tools ARM Embedded\4.8 2013q4\bin

Attention, change the version in the path, do not keep 4.8 2013q but use the one you installed instead.

Build script

To compile your homebrew sources to an executable binary file you can use either a Python script or a Makefile script. Makefile is easier, but this guide will also detail how the Python package is created to cover and understand all installation steps.

There are two packages ready to download: One for Python and one for Makefile, both made by Snailface. Just download the one you want and extract it in any folder. This will become your homebrew working folder. Create one copy per homebrew you are developing.

This is how the Python package has been created:

• Download the files from Kane49's github, and extract to a folder of your choice.
• Download the files from Naehrwert's gitHub, and extract the files and the folder into the p3ds folder from the previous download.
• For Linux users, download the modified build.py file from Tomiga to replace the one you downloaded from Kane49's repository.
• Open build.by and replace both instances of:

"-mcpu=mpcore -march=armv6k"

to

"-mcpu=arm946e-s -march=armv5te". 

• Comment the lines:

#run("copy Launcher.dat E:\\Launcher.dat > NUL")
#upload("Launcher.dat")
#run("del payload.bin")

Compiling .dat format

ARM9

If you are using Python to compile your homebrew:

• In your development folder, open a command line and type "Python build.py"
• You can also run Build.bat

If you are using makefile:

• In your development folder, open a command line and type "make"
• You can also run Build.bat

Your homebrew will be compiled as a Payload.bin and will be encapsulated into a Launcher.dat file ready to launch using a ROP exploit. You can provide both the .bin and .dat file when you share your homebrew.

ARM11

• Open a command line window and navigate to your homebrew folder and type "make".

It will create a <folder name of your project>.elf file.

To convert the elf file to .3ds format:

• Download MakeROM by 3DSGuy.
• Alternative Download Link
• Extract it to a new folder.
• If you don't want to make homebrew for Gateway 3DS flashcart, you can find file requirement and command line format to use with MakeROM on 3dbrew.org.

converting .elf to .3ds format

• If you want to make the .3ds file working on Gateway 3DS flashcart homebrew menu, download the Gateway Card Homebrew Files, by 3DSGuy, and extract its content into the Makerom folder.
• Open a command line window and navigate to the MakeROM folder.
• type

build <elf file> <output 3ds file>

where <elf.file> is the name of your homebrew.elf, and <output 3ds file> is the name of the .3ds file

example

build myproject.elf AwesomeGame.3ds

Making your own Homebrew Icon and Banner

If you want to create your own banner and icon for ARM11 homebrew, you can use 3DS Banner Maker, by Snailface, to convert png pictures to the correct format used by MakeROM. It requires Python 2 and PIL (Python Image Library).

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.

When you release the homebrew, provide (along the sources if your project is open) all the compiled files:

For ARM9 homebrew, the .bin and .dat file. If you want you can also provide both signed and unsigned .dat file to prevent the user to check if the file is signed or not, or tell the user if it's signed for Gateway ROP exploit or unsigned for the open source ROP exploit.

For ARM11 homebrew, the .elf and the .3ds file.

The elf and bin could be useful in case the file need to be repack later using a different makeROM (one for gateway 3DS, one for Smealum's Homebrew loader, etc.), or a different ROP exploit.

Elf file can also be used on 3DS Emulators (currently two available, Citra and 3DMoo ), while the .dat and .3ds format are not always supported or working fine.