cia-to-cci 0.1.7

Python library for converting Nintendo 3DS CIA files to decrypted CCI files

CIA to CCI Converter

A Python library with C/C++ bindings for converting Nintendo 3DS CIA (CTR Importable Archive) files to decrypted CCI (CTR Cart Image) files.

Features

• Zero External Dependencies: All tools (ctrtool, makerom) are statically linked into Python extension modules
• Full Decryption Support: Extracts and decrypts CXI components using AES keys
• Native Performance: C/C++ implementation with Python bindings via pybind11
• Cross-Platform: Works on macOS, Linux, and Windows
• Clean Python API: High-level interface for easy integration
• Low-Level Access: Direct access to ctrtool and makerom functionality

What This Tool Does

This library replicates the functionality of command-line tools ctrtool and makerom from the Project_CTR repository, packaged as a convenient Python library.

The conversion process:

1. Extracts contents from CIA files
2. Reads metadata (Title ID, Product Code) from CXI
3. Extracts and decrypts CXI components (ExeFS, RomFS, extended header)
4. Generates RSF configuration file with system calls and service access
5. Rebuilds decrypted CXI with all components
6. Creates final decrypted CCI file

Requirements

System Requirements

• Python: 3.8 or higher
• Platform: macOS, Linux, or Windows
• Build Tools (for building from source):
  • CMake 3.18+
  • C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2019+)
  • Python development headers

AES Keys (Required)

This tool requires Nintendo 3DS AES keys for decryption. You must provide your own keys at:

~/.3ds/aes_keys.txt

Important: This project does NOT include or provide AES keys. You must obtain them legally through your own means.

Installation

From Source

# Clone the repository with submodules
git clone --recursive https://github.com/reyrodrigues/cia-to-cci.git
cd cia-to-cci

# Build and install
pip install .

Development Installation

# Install in editable mode
pip install -e .

# Run tests
pytest tests/

Usage

Command-Line Interface

After installation, you can use the cia-to-cci command:

# Basic usage - converts game.cia to game.cci
cia-to-cci game.cia

# Specify output path
cia-to-cci game.cia -o output.cci

# Use custom AES keys file
cia-to-cci game.cia --keys /path/to/aes_keys.txt

# Keep temporary files for debugging
cia-to-cci game.cia --keep-temp

# Show help
cia-to-cci --help

You can also run it as a Python module:

python -m cia_to_cci game.cia

Python API

Basic Conversion

from cia_to_cci import convert_cia_to_cci

# Convert CIA to decrypted CCI
output_path = convert_cia_to_cci("game.cia", "game.cci")
print(f"Converted successfully: {output_path}")

Advanced Usage

from cia_to_cci import CIAConverter
from pathlib import Path

# Create converter with custom AES keys path
converter = CIAConverter(aes_keys_path=Path("custom/path/aes_keys.txt"))

# Convert with automatic output naming
output = converter.convert(Path("game.cia"))

Low-Level API

from cia_to_cci import ctrtool, makerom
from pathlib import Path
import tempfile

with tempfile.TemporaryDirectory() as temp_dir:
    temp_path = Path(temp_dir)

    # Step 1: Extract CIA contents
    main_content = ctrtool.extract_cia("game.cia", temp_path)

    # Step 2: Get CXI metadata
    info = ctrtool.get_cxi_info(main_content)
    print(f"Title ID: {info.title_id}")
    print(f"Product Code: {info.product_code}")

    # Step 3: Extract CXI components
    ctrtool.extract_cxi(
        cxi_path=main_content,
        exheader_path=temp_path / "exheader.bin",
        exefs_dir=temp_path / "exefs",
        romfs_path=temp_path / "romfs.bin",
        logo_path=temp_path / "logo.bin",
        plain_path=temp_path / "plain.bin",
        decompress_code=True
    )

    # Step 4: Build decrypted CXI
    cxi_output = makerom.build_cxi(
        output_path=temp_path / "decrypted.cxi",
        rsf_path=temp_path / "build.rsf",
        exheader_path=temp_path / "exheader.bin",
        code_path=temp_path / "exefs/code.bin",
        icon_path=temp_path / "exefs/icon.bin",
        banner_path=temp_path / "exefs/banner.bin",
        romfs_path=temp_path / "romfs.bin"
    )

    # Step 5: Build final CCI
    cci_output = makerom.build_cci(
        output_path="game.cci",
        content_path=cxi_output
    )

Building from Source

Prerequisites

Install build dependencies:

macOS:

brew install cmake python3

Ubuntu/Debian:

sudo apt-get install cmake python3-dev build-essential

Windows:

• Install Visual Studio 2019 or later with C++ build tools
• Install CMake
• Python 3.8+ from python.org

Build Steps

# Clone with submodules
git clone --recursive https://github.com/reyrodrigues/cia-to-cci.git
cd cia-to-cci

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate.bat

# Install in development mode
pip install -e .

Build Configuration

The project uses CMake for building native extensions. Build options:

# Release build (default) - optimized binaries
pip install -e .

# Debug build - for development
CMAKE_BUILD_TYPE=Debug pip install -e .

Project Structure

cia_to_cci/
├── src/
│   └── cia_to_cci/
│       ├── __init__.py          # Main package exports
│       ├── converter.py         # High-level conversion API
│       ├── ctrtool.py          # ctrtool wrapper
│       ├── makerom.py          # makerom wrapper
│       └── _bindings/          # C++ pybind11 bindings
├── native/
│   ├── project_ctr/           # Git submodule: Project_CTR
│   ├── ctrtool_wrapper/       # C++ wrapper for ctrtool
│   └── makerom_wrapper/       # C wrapper for makerom
├── tests/                     # Unit and integration tests
├── CMakeLists.txt            # Root build configuration
└── pyproject.toml            # Python package metadata

Dependencies

This project incorporates code from:

• Project_CTR - ctrtool and makerom (MIT License)
  • Copyright (c) 2014 3DSGuy
  • Copyright (c) 2014 applestash
  • Copyright (c) 2015-2022 Jakcron

All dependencies are statically linked, so no external installation is required.

Troubleshooting

"Failed to load cryptographic keys"

Ensure your AES keys file exists at ~/.3ds/aes_keys.txt and contains valid keys.

Build fails on macOS

Make sure you have Xcode Command Line Tools installed:

xcode-select --install

Build fails on Linux

Install Python development headers:

sudo apt-get install python3-dev

Build fails on Windows

Make sure you have:

• Visual Studio 2019 or later with C++ build tools installed
• CMake in your PATH
• Run the build from a Visual Studio Developer Command Prompt

ImportError when importing module

Rebuild the extension modules:

pip install --force-reinstall -e .

Legal Notice

Important: This tool is intended for legal use only, such as:

• Backup and preservation of games you legally own
• Development and homebrew purposes
• Educational use

Users are responsible for complying with all applicable laws regarding:

• Copyright and intellectual property
• DMCA and anti-circumvention statutes
• Software licensing agreements

This project does NOT provide or include:

• Nintendo 3DS AES keys
• Copyrighted game files
• Any circumvention tools

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Testing

# Run tests
pytest tests/

# Run with coverage
pytest --cov=cia_to_cci tests/

License

This project is licensed under the MIT License - see the LICENSE file for details.

This project incorporates code from Project_CTR, which is also MIT licensed.

Acknowledgments

• 3DSGuy, applestash, and Jakcron for the original ctrtool and makerom implementations
• Project_CTR contributors for maintaining the tools

---

Disclaimer: This tool is provided as-is for educational and legal purposes only. The authors are not responsible for any misuse of this software.