pyctr.type.cia module

Module for interacting with CTR Importable Archive (CIA) files.

exception pyctr.type.cia.CIAError[source]

Bases: PyCTRError

Generic error for CIA operations.

exception pyctr.type.cia.InvalidCIAError[source]

Bases: CIAError

Invalid CIA header exception.

class pyctr.type.cia.CIASection(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Sections of a CIA file. Values 0 and above are only for the most common types, and do not apply to DLC titles.

ArchiveHeader = -4

Contains the sizes of all the other sections.

CertificateChain = -3

Contains signatures used to verify the Ticket and Title Metadata.

Ticket = -2

Contains the title key used to decrypt the contents, as well as a content index describing which contents are enabled (mostly used for DLC).

TitleMetadata = -1

Contains information about all the possible contents.

Application = 0

Main application CXI.

Manual = 1

Manual CFA. It has a RomFS with a single “Manual.bcma” file inside.

DownloadPlayChild = 2

Download Play Child CFA. It has a RomFS with CIA files that are sent to other Nintendo 3DS systems using Download Play. Most games only contain one.

Meta = -5
class pyctr.type.cia.CIARegion(section, offset, size, iv)[source]

Bases: NamedTuple

Parameters:
section: int | CIASection

Index of the section.

offset: int

Offset of the entry, relative to the end of the header.

size: int

Size of the entry data.

iv: bytes

Initialization vector. Only used for encrypted contents.

class pyctr.type.cia.CIAReader(file, *, fs=None, closefd=None, case_insensitive=True, crypto=None, dev=False, seed=False, load_contents=True)[source]

Bases: TypeReaderCryptoBase

Reads the contents of CIA files. The sources of these are usually dumps from digital titles from Nintendo eShop or the update CDN, Game Card update partitions, or Download Play children.

Only NCCH contents are supported. SRL (DSiWare) contents are currently ignored.

CIA files contain:

  • a 0x20-byte header with sizes for all the following sections

  • an archive header where each bit is an enabled content

  • a Certificate chain to verify the signatures in all the following sections

  • a Ticket with a Title Key to decrypt the contents

  • a Title Metadata (TMD) that contains information about all the possible contents

  • the contents themselves

  • an optional Meta region

In executable titles, the first content is the CTR Executable Image (CXI), second is a manual in a CTR File Archive (CFA), and third is a Download Play child container in a CFA. In DLC titles (tid-high is 0004008c), the first content has meta information about each content, then the rest contain the DLC content. All contents are CFAs. In system archives, the first (and only) content is a CFA.

CIA files do not always contain all the contents in the TMD, especially in dumped DLC titles. Which contents are in the archive is indicated in the archive header.

Note that a custom CryptoEngine object is only used for encryption on the CIA contents. Each NCCHReader must use their own object, as it can only store keys for a single NCCH container. To use a custom one, set load_contents to False, then load each section manually with open_raw_section.

Parameters:

  • file (FilePathOrObject) – A file path or a file-like object with the CIA data.

  • case_insensitive (bool) – Use case-insensitive paths for the RomFS of each NCCH container.

  • crypto (CryptoEngine) – A custom CryptoEngine object to be used. Defaults to None, which causes a new one to be created. This is only used to decrypt the CIA, not the NCCH contents.

  • dev (bool) – Use devunit keys.

  • seed (bytes) – Seed to use. This is a quick way to add a seed using add_seed().

  • load_contents (bool) – Load each partition with NCCHReader.

  • fs (Optional[FS]) –

  • closefd (bool) –

sections: Dict[int | CIASection, CIARegion]

A list of CIARegion objects containing the offset and size of each section.

contents: Dict[int, NCCHReader]

A dict of NCCHReader objects for each active NCCH content.

content_info: List[ContentChunkRecord]

A list of ContentChunkRecord objects for each active content.

total_size: int

Expected size of the CIA file in bytes.

tmd: TitleMetadataReader

The TitleMetadataReader object with information from the TMD section.

open_raw_section(section)[source]

Open a raw CIA section for reading with on-the-fly decryption.

Parameters:

section (Union[int, CIASection]) – The section to open.

Returns:

A file-like object that reads from the section.

Return type:

SubsectionIO