Toggle search
Toggle menu
12.1K
15.1K
1.2K
216.7K
GameBrew
Toggle preferences menu
Toggle personal menu
Not logged in
Your IP address will be publicly visible if you make any edits.

3dsconv: Difference between revisions

From GameBrew
More actions
Created page with "{{Infobox 3DS Homebrews |title=3dsconv |image=3dsconv.png |description=Python script to convert Nintendo 3DS CCI ("".cci"", "".3ds"") files to the CIA format. |author=ihaveamac |lastupdated=2017/08/03 |type=PC Utilities |version=4.2 |license=MIT |download=https://dlhb.gamebrew.org/3dshomebrews/3dsconv.7z |website=https://gbatemp.net/threads/3dsconv-py-script-to-easily-convert-3ds-roms-to-cia.428248/ |source=https://github.com/ihaveamac/3dsconv |donation= }} {{#seo: |titl..."
 
No edit summary
 
Line 19: Line 19:
|image_alt=3dsconv
|image_alt=3dsconv
}}
}}
'''3dsconv''' is a Python 3 script developed by [https://github.com/ihaveamac/3dsconv 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.
3dsconv.py is a Python 3 tool that converts Nintendo 3DS game dumps (in .cci or .3ds format) into installable .cia files, the format used for installing games directly to your 3DS home menu.


== Features ==
It supports CCI that is decrypted, encrypted using zerokey, or the original NCCH (slot 0x2C).
* '''Format Conversion''': Transforms CCI (.3ds/.cci) files into CIA format, facilitating game installation on 3DS systems.
* Encryption requires [https://github.com/ricmoo/pyaes pyaes] (<code>pip install pyaes</code>).
* '''Encryption Detection''': Automatically identifies if a CCI file is decrypted, encrypted using original NCCH (slot 0x2C), or encrypted with zerokey.
* Original NCCH encryption requires [https://github.com/ihaveamac/3dsconv#encryption a dump of the protected ARM9 bootROM].
* '''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 (<code>3dsconv.exe</code>) for Windows users, eliminating the need for a separate Python installation.


== Usage ==
== User guide ==
=== Basic use ===
=== Basic use (Windows) ===
On Windows, CCIs can be dragged on top of <code>3dsconv.exe</code>. See Encryption section for details about encrypted files.
Just drag and drop your <code>.3ds</code> or <code>.cci</code> file onto <code>3dsconv.exe</code>


=== Advanced options ===
(Note: For encrypted files, see the Encryption section below.)
3dsconv can be used as a standalone script, or installed using <code>python3 setup.py install</code>.


<pre class="language-shell">python3 3dsconv.py [options] game.3ds [game.3ds ...]</pre>
=== Command line ===
* <code>--output=&lt;dir&gt;</code> - Save converted files in specified directory; default is current directory or value of variable <code>output-directory</code>
You can run it as a standalone script or install it with:
* <code>--boot9=&lt;file&gt;</code> - Path to dump of protected ARM9 bootROM
python3 setup.py install
* <code>--overwrite</code> - Overwrite existing converted files
* <code>--ignore-bad-hashes</code> - Ignore invalid hashes and CCI files and convert anyway
* <code>--ignore-encryption</code> - Ignore the encryption header value, assume the ROM as unencrypted
* <code>--verbose</code> - Print more information
* <code>--dev-keys</code> - Use developer-unit keys


== Encryption ==
Basic command:
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:
python3 3dsconv.py [options] game.3ds [game2.3ds ...]


* Value of option <code>--boot9=</code> or variable <code>boot9_path</code>, if set
Options:
* <code>boot9.bin</code> (full) in current working directory
* <code>--output=&lt;dir&gt;</code> - Save converted files to a custom folder (default: current directory or <code>output-directory</code> variable).
* <code>boot9_prot.bin</code> (protected) in current working directory
** <code>--boot9=&lt;file&gt;</code> - Path to your <code>ARM9 bootROM</code> dump.
* <code>~/.3ds/boot9.bin</code> (full)
** <code>--overwrite</code> - Replace existing <code>.cia</code> files.
* <code>~/.3ds/boot9_prot.bin</code> (protected)
** <code>--ignore-bad-hashes</code> - Convert even if file hashes are invalid.
** <code>--ignore-encryption</code> - Treat the file as unencrypted.
** <code>--verbose</code> - Show detailed conversion info.
** <code>--dev-keys</code> - Use developer-unit keys.


boot9strap is required to dump. Setup can be found at [https://3ds.guide/ 3DS Guide]. Hold START+SELECT+X at boot to dump to <code>sdmc:/boot9strap/boot9.bin</code>.
=== Encryption requirements ===
To decrypt games using original NCCH encryption (slot <code>0x2C</code>), you’ll need a copy of the 3DS ARM9 bootROM (either <code>boot9.bin</code> or <code>boot9_prot.bin</code>).


boot9 SHA256: <code>2f88744feed717856386400a44bba4b9ca62e76a32c715d4f309c399bf28166f</code><br />
The file is checked in the order of:
boot9_prot SHA256: <code>7331f7edece3dd33f2ab4bd0b3a5d607229fd19212c10b734cedcaf78c1a7b98</code>
* Path set by <code>--boot9=</code> or <code>boot9_path</code>
* <code>boot9.bin</code> (full) in the current folder
* <code>boot9_prot.bin</code> (protected) in the current folder
* <code>~/.3ds/boot9.bin</code> (full)
* <code>~/.3ds/boot9_prot.bin</code> (protected)


== Developer titles (not fully tested) ==
How to dump your bootROM:
Conversion for developer-unit systems is possible with <code>--dev-keys</code>. 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.
* Use boot9strap (follow [https://3ds.guide/ 3DS Guide]).
* Hold Start+Select+X while booting to dump to <code>sdmc:/boot9strap/boot9.bin</code>.


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.
SHA-256 checksums (to verify your dump):
 
* <code>boot9.bin</code>: <code>2f88744feed717856386400a44bba4b9ca62e76a32c715d4f309c399bf28166f</code>
The dev certchain must be provided. The file is searched for is <code>certchain-dev.bin</code> in current working directory, or <code>~/.3ds/certchain-dev.bin</code>.
* <code>boot9_prot.bin</code>: <code>7331f7edece3dd33f2ab4bd0b3a5d607229fd19212c10b734cedcaf78c1a7b98</code>
 
To extract from a dev CIA, use <code>ctrtool --certs=certchain-dev.bin title.cia</code>.
 
SHA256: <code>7921ae82c9dcf411351314f2fe2c67378c6a872d2524f71b3c002b4d4a56846f</code>
 
== Pack into standalone executable for Windows ==
Using [https://pypi.python.org/pypi/py2exe/ 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. [https://www.python.org/downloads/release/python-344/ 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 (<code>cmd.exe</code>) in the current directory.
# Run <code>py -3.4 -m py2exe.build_exe 3dsconv.py -b 0</code>. See the [https://pypi.python.org/pypi/py2exe/ py2exe page] for more options.
# <code>3dsconv.exe</code> will be in <code>dist</code> after it finishes. If anything but <code>0</code> was used for <code>-b</code>/<code>--bundle-files</code>, dependencies will also be saved.


==Changelog==
==Changelog==
'''v4.2'''
'''v4.2'''
* Fix conversion of titles with a dlp-child but no manual ([https://gbatemp.net/posts/7326476/ gbatemp])
* Fix conversion of titles with a dlp-child but no manual ([https://gbatemp.net/posts/7326476/ gbatemp]).
* Now installable using setuptools, download source code and use <code>python3 setup.py install</code> ([https://github.com/ihaveamac/3dsconv/pull/13 #13], thanks [https://github.com/dr1s @dr1s])
* Now installable using setuptools, download source code and use <code>python3 setup.py install</code> ([https://github.com/ihaveamac/3dsconv/pull/13 #13], thanks [https://github.com/dr1s @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.
* 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'''
'''v4.1'''
* Generate Meta region, for use with FBI and other tools
* Generate Meta region, for use with FBI and other tools.
* Some more code cleanup
* Some more code cleanup.
'''v4.0'''
'''v4.0'''
* Rewrite for Python 3 - 2.x is no longer supported
* Rewrite for Python 3 - 2.x is no longer supported.
* Use pyaes instead of PyCrypto[dome]
* Use pyaes instead of PyCrypto[dome].
* bootROM keys support - see README for details on usage
* bootROM keys support - see README for details on usage.
* XORpad support removed
* XORpad support removed.
* Rewritten output messages
* Rewritten output messages.
* Other things I might have forgotten about
* Other things I might have forgotten about.
'''v3.21'''
'''v3.21'''
* Fix encrypted CCIs improperly being detected as zerokey encrypted ([https://github.com/ihaveamac/3dsconv/pull/8 #8], thanks [https://github.com/putnam @putnam])
* Fix encrypted CCIs improperly being detected as zerokey encrypted ([https://github.com/ihaveamac/3dsconv/pull/8 #8], thanks [https://github.com/putnam @putnam]).
* Fix bad <code>ncchinfo.bin</code> generation (wrong block size)
* Fix bad <code>ncchinfo.bin</code> generation (wrong block size).
'''v3.2'''
'''v3.2'''
* New: Zerokey crypto support without XORpads
* New: Zerokey crypto support without XORpads.
** PyCrypto is required. This can be installed with pip.
** 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.
** 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: <code>--ignorebadhash</code> to ignore bad SHA-256 hash of the ExHeader (is this even that useful?)
* New: <code>--ignorebadhash</code> to ignore bad SHA-256 hash of the ExHeader (is this even that useful?)
* Code cleanup and other things
* Code cleanup and other things.
'''v3.1'''
'''v3.1'''
* Show percentage for each partition
* Show percentage for each partition.
* Other minor changes
* Other minor changes.
'''v3.0'''
'''v3.0'''
*Manually builds the CIA now; makerom is no longer needed
*Manually builds the CIA now; makerom is no longer needed.
**This should mean lower-memory computers can properly convert larger games.
**This should mean lower-memory computers can properly convert larger games.
'''v2.2'''
'''v2.2'''
* Switched dependency from make_cia -&gt; makerom (too many issues with make_cia, not worth it anymore)
* Switched dependency from make_cia -&gt; makerom (too many issues with make_cia, not worth it anymore).
** This should fix any issues with Manual/Download Play not working ([https://github.com/ihaveamac/3dsconv/issues/5 #5])
** This should fix any issues with Manual/Download Play not working ([https://github.com/ihaveamac/3dsconv/issues/5 #5]).
'''v2.16'''
'''v2.16'''
* py2exe support for building a single .exe for Windows
* py2exe support for building a single .exe for Windows.
* Other small fixes
* Other small fixes.
'''v2.15'''
'''v2.15'''
*Fix ncchinfo.bin generation again (not generating sometimes with just --gen-ncchinfo unless --gen-ncch-all was used).
*Fix ncchinfo.bin generation again (not generating sometimes with just --gen-ncchinfo unless --gen-ncch-all was used).
Line 118: Line 106:
*Fix ncchinfo.bin generation (wrong variable used).
*Fix ncchinfo.bin generation (wrong variable used).
'''v2.13'''
'''v2.13'''
* Fix: close Manual/Download Play child container before deleting (only seemed to be an issue on Windows)
* Fix: close Manual/Download Play child container before deleting (only seemed to be an issue on Windows).
* Fix: output folder not being created (?)
* Fix: output folder not being created (?)
* Temporary work directory can be changed (variable workdir)
* Temporary work directory can be changed (variable workdir).
* make_cia more verbose if --verbose is used
* make_cia more verbose if --verbose is used.
* Cleanup (tabs to spaces, re-organize code order, etc.)
* Cleanup (tabs to spaces, re-organize code order, etc.)
'''v2.12'''
'''v2.12'''
Line 129: Line 117:
*Fix ncchinfo.bin generation (generating a bad "Counter").
*Fix ncchinfo.bin generation (generating a bad "Counter").
'''v2.1'''
'''v2.1'''
* 3dstool is no longer used, only [https://github.com/ihaveamac/ctr_toolkit make_cia] is required now
* 3dstool is no longer used, only [https://github.com/ihaveamac/ctr_toolkit make_cia] is required now.
* New: <code>--overwrite</code> - overwrite any existing converted CIA, if it exists
* New: <code>--overwrite</code> - overwrite any existing converted CIA, if it exists.
* New: <code>--gen-ncchinfo</code> - generate <code>ncchinfo.bin</code> for roms that don't have a valid xorpad
* New: <code>--gen-ncchinfo</code> - generate <code>ncchinfo.bin</code> for roms that don't have a valid xorpad.
** <code>ncchinfo_gen_exheader.py</code> is no longer included
** <code>ncchinfo_gen_exheader.py</code> is no longer included.
* New: <code>--gen-ncch-all</code> - use with <code>--gen-ncchinfo</code> to generate an <code>ncchinfo.bin</code> for all roms
* New: <code>--gen-ncch-all</code> - use with <code>--gen-ncchinfo</code> to generate an <code>ncchinfo.bin</code> for all roms.
* New: <code>--noconvert</code> - don't convert roms, useful if you just want to generate <code>ncchinfo.bin</code>
* New: <code>--noconvert</code> - don't convert roms, useful if you just want to generate <code>ncchinfo.bin</code>
* Fix converting decrypted roms with both Manual and Download Play child container
* Fix converting decrypted roms with both Manual and Download Play child container.
* Various other changes
* Various other changes.
'''v2.01'''
'''v2.01'''
* Fixes potential hanging trying to check if a command exists
* Fixes potential hanging trying to check if a command exists.
* Fixes converting a .3ds to a .cia if the .cia already exists on Windows
* Fixes converting a .3ds to a .cia if the .cia already exists on Windows.
'''v2.0'''
'''v2.0'''
* First Release.
* First Release.
Line 149: Line 137:


== External links ==
== External links ==
* Gbatemp - https://gbatemp.net/threads/3dsconv-py-script-to-easily-convert-3ds-roms-to-cia.428248/
* GitHub - https://github.com/ihaveamac/3dsconv
* Github - https://github.com/ihaveamac/3dsconv
* GBAtemp - https://gbatemp.net/threads/3dsconv-py-script-to-easily-convert-3ds-roms-to-cia.428248/

Latest revision as of 03:23, 4 May 2025

3dsconv
General
Authorihaveamac
TypePC Utilities
Version4.2
LicenseMIT License
Last Updated2017/08/03
Links
Download
Website
Source

3dsconv.py is a Python 3 tool that converts Nintendo 3DS game dumps (in .cci or .3ds format) into installable .cia files, the format used for installing games directly to your 3DS home menu.

It supports CCI that is decrypted, encrypted using zerokey, or the original NCCH (slot 0x2C).

User guide

Basic use (Windows)

Just drag and drop your .3ds or .cci file onto 3dsconv.exe

(Note: For encrypted files, see the Encryption section below.)

Command line

You can run it as a standalone script or install it with: 

python3 setup.py install

Basic command: 

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

Options:

  • --output=<dir> - Save converted files to a custom folder (default: current directory or output-directory variable).
    • --boot9=<file> - Path to your ARM9 bootROM dump.
    • --overwrite - Replace existing .cia files.
    • --ignore-bad-hashes - Convert even if file hashes are invalid.
    • --ignore-encryption - Treat the file as unencrypted.
    • --verbose - Show detailed conversion info.
    • --dev-keys - Use developer-unit keys.

Encryption requirements

To decrypt games using original NCCH encryption (slot 0x2C), you’ll need a copy of the 3DS ARM9 bootROM (either boot9.bin or boot9_prot.bin).

The file is checked in the order of:

  • Path set by --boot9= or boot9_path
  • boot9.bin (full) in the current folder
  • boot9_prot.bin (protected) in the current folder
  • ~/.3ds/boot9.bin (full)
  • ~/.3ds/boot9_prot.bin (protected)

How to dump your bootROM:

  • Use boot9strap (follow 3DS Guide).
  • Hold Start+Select+X while booting to dump to sdmc:/boot9strap/boot9.bin.

SHA-256 checksums (to verify your dump):

  • boot9.bin: 2f88744feed717856386400a44bba4b9ca62e76a32c715d4f309c399bf28166f
  • boot9_prot.bin: 7331f7edece3dd33f2ab4bd0b3a5d607229fd19212c10b734cedcaf78c1a7b98

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

Retrieved from "https://www.gamebrew.org/index.php?title=3dsconv&oldid=199917"

Advertising: