3dsconv

3dsconv
3dsconv
General
Author	ihaveamac
Type	PC Utilities
Version	4.2
License	MIT License
Last Updated	2017/08/03
Links
	Download
	Website
	Source

3dsconv is a Python 3 script developed by ihaveamac designed to convert Nintendo 3DS CTR Cart Image files (CCI, with extensions ".cci" or ".3ds") into the CTR Importable Archive format (CIA). This tool is particularly useful for users who wish to install 3DS games on systems with custom firmware.

Features

Format Conversion: Transforms CCI (.3ds/.cci) files into CIA format, facilitating game installation on 3DS systems.
Encryption Detection: Automatically identifies if a CCI file is decrypted, encrypted using original NCCH (slot 0x2C), or encrypted with zerokey.
Offline Decryption: Supports reading the ARM9 bootROM for encryption keys, allowing complete offline decryption and conversion.
Developer Unit Support: Enables conversion of titles for use on developer units, including those encrypted with dev-unit keys.
Windows Compatibility: Provides a standalone executable (3dsconv.exe) for Windows users, eliminating the need for a separate Python installation.

Usage

Basic use

On Windows, CCIs can be dragged on top of 3dsconv.exe. See Encryption section for details about encrypted files.

Advanced options

3dsconv can be used as a standalone script, or installed using python3 setup.py install.

python3 3dsconv.py [options] game.3ds [game.3ds ...]

--output=<dir> - Save converted files in specified directory; default is current directory or value of variable output-directory
--boot9=<file> - Path to dump of protected ARM9 bootROM
--overwrite - Overwrite existing converted files
--ignore-bad-hashes - Ignore invalid hashes and CCI files and convert anyway
--ignore-encryption - Ignore the encryption header value, assume the ROM as unencrypted
--verbose - Print more information
--dev-keys - Use developer-unit keys

Encryption

3dsconv requires the Nintendo 3DS full or protected ARM9 bootROM to decrypt files using Original NCCH encryption (slot 0x2C). The file is checked for in the order of:

Value of option --boot9= or variable boot9_path, if set
boot9.bin (full) in current working directory
boot9_prot.bin (protected) in current working directory
~/.3ds/boot9.bin (full)
~/.3ds/boot9_prot.bin (protected)

boot9strap is required to dump. Setup can be found at 3DS Guide. Hold START+SELECT+X at boot to dump to sdmc:/boot9strap/boot9.bin.

boot9 SHA256: 2f88744feed717856386400a44bba4b9ca62e76a32c715d4f309c399bf28166f
boot9_prot SHA256: 7331f7edece3dd33f2ab4bd0b3a5d607229fd19212c10b734cedcaf78c1a7b98

Developer titles (not fully tested)

Conversion for developer-unit systems is possible with --dev-keys. This is required for titles encrypted using dev-unit keys (only seems to be used for SystemUpdater). Titles encrypted with retail keys can't be converted this way without external decryption.

This does not decrypt or change the encryption of the output file, therefore CIAs will still only work on dev-units without separate decryption or changing encryption.

The dev certchain must be provided. The file is searched for is certchain-dev.bin in current working directory, or ~/.3ds/certchain-dev.bin.

To extract from a dev CIA, use ctrtool --certs=certchain-dev.bin title.cia.

SHA256: 7921ae82c9dcf411351314f2fe2c67378c6a872d2524f71b3c002b4d4a56846f

Pack into standalone executable for Windows

Using py2exe for Python 3, you can pack the script into a Windows executable, primarily for use on a computer without Python, or for easy use in the Windows Command Prompt. Python 3.4 is required, 3.5 or later is currently not supported.

Clone or download the repository, or the latest release.
Open the Windows Command Prompt (cmd.exe) in the current directory.
Run py -3.4 -m py2exe.build_exe 3dsconv.py -b 0. See the py2exe page for more options.
3dsconv.exe will be in dist after it finishes. If anything but 0 was used for -b/--bundle-files, dependencies will also be saved.

Changelog

v4.2

Fix conversion of titles with a dlp-child but no manual (gbatemp)
Now installable using setuptools, download source code and use python3 setup.py install (#13, thanks @dr1s)
Titles can be converted for use on dev-units (not fully tested), including those encrypted with dev-unit keys. See README for usage and limitations.

v4.1

Generate Meta region, for use with FBI and other tools
Some more code cleanup

v4.0

Rewrite for Python 3 - 2.x is no longer supported
Use pyaes instead of PyCrypto[dome]
bootROM keys support - see README for details on usage
XORpad support removed
Rewritten output messages
Other things I might have forgotten about

v3.21

Fix encrypted CCIs improperly being detected as zerokey encrypted (#8, thanks @putnam)
Fix bad ncchinfo.bin generation (wrong block size)

v3.2

New: Zerokey crypto support without XORpads
- PyCrypto is required. This can be installed with pip.
- This does not decrypt the contents of the CIA. Custom firmwares today don't support zerokey, only Gateway and Nintendo developer tools/firmware at the moment. Decrypt the CIA with Decrypt9 before installing. Decryption might come later, depending if custom firmwares support zerokey anytime soon.
New: --ignorebadhash to ignore bad SHA-256 hash of the ExHeader (is this even that useful?)
Code cleanup and other things

v3.1

Show percentage for each partition
Other minor changes

v3.0

Manually builds the CIA now; makerom is no longer needed
- This should mean lower-memory computers can properly convert larger games.

v2.2

Switched dependency from make_cia -> makerom (too many issues with make_cia, not worth it anymore)
- This should fix any issues with Manual/Download Play not working (#5)

v2.16

py2exe support for building a single .exe for Windows
Other small fixes

v2.15

Fix ncchinfo.bin generation again (not generating sometimes with just --gen-ncchinfo unless --gen-ncch-all was used).

v2.14

Fix ncchinfo.bin generation (wrong variable used).

v2.13

Fix: close Manual/Download Play child container before deleting (only seemed to be an issue on Windows)
Fix: output folder not being created (?)
Temporary work directory can be changed (variable workdir)
make_cia more verbose if --verbose is used
Cleanup (tabs to spaces, re-organize code order, etc.)

v2.12

Wildcard support for Windows (because the command prompt doesn't support it for some reason).
Properly close rom in case ExHeader hash check fails.

v2.11

Fix ncchinfo.bin generation (generating a bad "Counter").

v2.1

3dstool is no longer used, only make_cia is required now
New: --overwrite - overwrite any existing converted CIA, if it exists
New: --gen-ncchinfo - generate ncchinfo.bin for roms that don't have a valid xorpad
- ncchinfo_gen_exheader.py is no longer included
New: --gen-ncch-all - use with --gen-ncchinfo to generate an ncchinfo.bin for all roms
New: --noconvert - don't convert roms, useful if you just want to generate ncchinfo.bin
Fix converting decrypted roms with both Manual and Download Play child container
Various other changes

v2.01

Fixes potential hanging trying to check if a command exists
Fixes converting a .3ds to a .cia if the .cia already exists on Windows

v2.0

First Release.

License / Credits

3dsconv.py and pyaes are under the MIT license.

For versions older than "2.0", see this Gist.

External links