Changes

[[Category:File formats]]

[[Category:File formats]]

The following text tries to document the structure of the NCCH container format.

The following text tries to document the structure of the NCCH (Nintendo Content Container Header) container format. This format is used to store the content of any installed [[Titles|title]].

== Overview ==

== Overview ==

There are two known NCCH container specialisations used on the 3DS, "executable" and "non-executable", officially known as CXI and CFA respectively.

There are two known NCCH container specializations used on the 3DS, "executable" and "non-executable", officially known as CXI and CFA, respectively.

== CXI ==  

=== CXI ===

The CXI (CTR Executable Image) specialisation of the NCCH container, contains executable code, which runs on a single ARM11 core. It can communicate through SVC calls with the other ARM11 core running the 'system' program code. For reasons of clarity, the ARM11 cores will sometimes be called the 'appcore' and 'syscore' respectively.

The CXI (CTR Executable Image) specialization of the NCCH container contains executable code, which runs on a single ARM11 core.

The CXI format is structured in the following order:

The CXI format is structured in the following order:

* first a NCCH header,

* first a NCCH header,

* followed by an extended header,

* followed by an [[NCCH/Extended Header|extended header]],

* followed by an access descriptor,

* followed by an access descriptor,

* followed by an '''optional''' plain binary region,

* followed by an '''optional''' plain binary region,

The plain binary region is an area specifically stored in plaintext, mostly containing SDK library strings for identification.

The plain binary region is an area specifically stored in plaintext, mostly containing SDK library strings for identification.

== CFA ==

=== CFA ===

The CFA (CTR File Archive) specialisation of the NCCH container, is not executable, but are used in conjunction with CXI files. For instance the DLP Child Container and the Electronic Manual. (There is a system update NCCH which follows this format, but is used by the 3DS rather than the Application NCCH, and only works when embedded in the [[CCI]] format because the nVer is kept in the header of retail [[CCI]] files instead of the application NCCH). There are CFA files which exist alone in a title, but these are just [[Title list|System Data Archive]] titles and are found only in the [[Flash Filesystem#CTR partition|NAND]].

The CFA (CTR File Archive) specialization of the NCCH container is not executable, but is used in conjunction with CXI files, e.g. the DLP Child Container and the Electronic Manual. (There is a system update NCCH which follows this format, but is used by the 3DS rather than the Application NCCH, and only works when embedded in the [[CCI]] format because the nVer is kept in the header of retail [[CCI]] files instead of the application NCCH). There are CFA files which exist alone in a title, but these are just [[Title list|System Data Archive]] titles and are found only in the [[Flash Filesystem#CTR partition|NAND]].

CFA files are structured in the following order:

CFA files are structured in the following order:

* followed by an '''optional''' read-only filesystem ([[RomFS]])

* followed by an '''optional''' read-only filesystem ([[RomFS]])

== NCCH Specs ==

== Container File Format ==

=== Encryption ===

=== Encryption ===

The extended header, the [[ExeFS]], and the [[RomFS]] are encrypted using [https://github.com/3dshax/ctr/blob/master/ctrtool/ncch.c 128-bit AES CTR]. The decryption key is generated using the [[AES|AES Engine]] key generator, where the keyX is set by the bootrom (see below for the keyslots). Initially, the keyY was set to the first 0x10 bytes of the NCCH signature ("secure-crypto"). Later firmware updates introduced more sophisticated algorithms.

The extended header, the [[ExeFS]], and the [[RomFS]] are encrypted using [https://github.com/3dshax/ctr/blob/master/ctrtool/ncch.c 128-bit AES CTR] unless the NoCrypto flag is set in ncchflag[7]. There are different sets of encryption parameters in use, as over the time new system updates introduced more sophisticated means of encryption. Generally, the decryption key is generated using the [[AES|AES Engine]] key generator by selecting a particular key slot (see below), the keyX of which is usually set by the bootrom and keyY of which was originally set to the first 0x10 bytes of the NCCH signature.

 

'''NOTE: For a full understanding of the steps involved in decryption, consult the [https://github.com/Relys/Project_CTR ctrtool] and [https://github.com/archshift/Decrypt9 Decrypt9] source code instead.'''.

Starting with [[9.6.0-24|9.6.0-X]] Process9, there is a different method of generating the NCCH keyY which is enabled by setting the bitmask 0x20 in ncchflag[7]: The keyY will be set to a SHA256 hash generated with the 0x20 bytes of data constituted by the old-method-keyY and a unique content lock seed (each of which are 0x10 bytes wide), where seeds for downloaded titles that use the new crypto are stored in [[Filesystem_services#SEEDDB|SEEDDB]] (nand:/data/<console-unique>/sysdata/0001000f/00000000). The decryption is transparent to ARM11 userland: When FSUSER OpenFile is used with a NCCH archive which uses this crypto, the FS-module will add the seed-data from SEEDDB to the end of the file lowpath used for [[FSPXI:OpenFile]], using which Process9 then gets the hash for calculating the NCCH keyY. It has been observed that this new keyY generation is only used for [[RomFS]] and for [[ExeFS]] sections other than "icon" and "banner" (the same sections which would be used for the additional NCCH keyslots, however this keyY generation can be used without any additional NCCH keyslot). Not applying the encryption to "icon" and "banner" was presumably done to support pre-loading of games from the eShop (i.e. being able to download and install titles without being able to start them until official release).

Starting with [[9.6.0-24|9.6.0-X]] Process9, there is a different method of generating the NCCH keyY which is enabled by setting the bitmask 0x20 in ncchflag[7]: The keyY will be set to a SHA256 hash generated with the 0x20 bytes of data constituted by the old-method-keyY and a unique content lock seed (each of which are 0x10 bytes wide), where seeds for downloaded titles that use the new crypto are stored in [[Filesystem_services#SEEDDB|SEEDDB]] (nand:/data/<console-unique>/sysdata/0001000f/00000000). The decryption is transparent to ARM11 userland: When FSUSER OpenFile is used with a NCCH archive which uses this crypto, the FS-module will add the seed-data from SEEDDB to the end of the file lowpath used for [[FSPXI:OpenFile]], using which Process9 then gets the hash for calculating the NCCH keyY. It has been observed that this new keyY generation is only used for [[RomFS]] and for [[ExeFS]] sections other than "icon" and "banner" (the same sections which would be used for the additional NCCH keyslots, however this keyY generation can be used without any additional NCCH keyslot). Not applying the encryption to "icon" and "banner" was presumably done to support pre-loading of games from the eShop (i.e. being able to download and install titles without being able to start them until official release).

As of [[7.0.0-13|7.0.0-X]] the system supports a new encryption method for secure-crypto (when ncchflag[3] != 0). Where a second key is generated using the same keyY but with another [[AES|keyslot]]. The second key is used to crypt the [[RomFS]] and [[ExeFS]] files which don't have filenames "icon" or "banner" (i.e. ".code" and ".firm"). While everything else is crypted with the original key. Note the CTR used is the same for both keys. This makes titles "recognizable" but not "launchable" on systems which don't support this method or the keyslot used.

As of [[7.0.0-13|7.0.0-X]] the system supports a new encryption method for secure-crypto (when ncchflag[3] != 0). Where a second key is generated using the same keyY but with another [[AES|keyslot]]. The second key is used to crypt the [[RomFS]] and [[ExeFS]] files which don't have filenames "icon" or "banner" (i.e. ".code" and ".firm"). While everything else is crypted with the original key. Note the CTR used is the same for both keys. This makes titles "recognizable" but not "launchable" on systems which don't support this method or the keyslot used.

See below for the keyslots used for the additional NCCH keyslots. On Old3DS, as of [[9.6.0-24|9.6.0-X]], Process9 will *only* use keyslot 0x25 when ncchflag[3] is non-zero.

See below for the secondary keyslots used in NCCH crypto(as mentioned above). As of [[9.6.0-24|9.6.0-X]], Old3DS Process9 will *only* use secondary-keyslot 0x25 when ncchflag[3] is non-zero.

{| class="wikitable" border="1"

{| class="wikitable" border="1"

|-

|-

!  FW Introduced

!  FW Introduced

!  Old3DS

!  Old3DS

!  AES Keyslot

!  [[AES#Keyslot|AES Keyslots]]

!  Notes

!  Notes

|-

|-

|  0x01

|  0x01

|  [[7.0.0-13|7.0.0-X]]

|  [[7.0.0-13|7.0.0-X]]

|  style="background: green" | Yes

|  style="background: #ccffbb" | Yes

|  0x25

|  0x25

|  This keyslot is [[Savegames|initialized]] by the 6.0 gamecard savegame keyY init function during boot, using a different portion of the [[Savegames|final]] hash (this keyslot is separate from the one used for the 6.0 save crypto).

|  This keyslot is [[Savegames|initialized]] by the 6.0 gamecard savegame keyY init function during boot, using a different portion of the [[Savegames|final]] hash (this keyslot is separate from the one used for the 6.0 save crypto).

|  0x0A

|  0x0A

|  [[9.3.0-21|9.3.0-X]]

|  [[9.3.0-21|9.3.0-X]]

|  style="background: red" | No

|  style="background: #ffccbb" | No

|  0x18

|  0x18

|  This keyslot is initialized by [[FIRM#New_3DS_FIRM|arm9loader]] on New3DS starting with [[8.1.0-0_New3DS]], but only [[9.3.0-21|9.3.0-X]] and later know how to use it with ncchflag[3].

|  This keyslot is initialized by [[FIRM#New_3DS_FIRM|arm9loader]] on New3DS starting with [[8.1.0-0_New3DS]], but only [[9.3.0-21|9.3.0-X]] and later know how to use it with ncchflag[3].

|  0x0B

|  0x0B

|  [[9.6.0-24|9.6.0-X]]

|  [[9.6.0-24|9.6.0-X]]

|  style="background: red" | No

|  style="background: #ffccbb" | No

|  0x1B

|  0x1B

|  [[9.6.0-24|9.6.0-X]]'s [[FIRM#New_3DS_FIRM|arm9loader]] changed the contents of keyslots 0x19-0x1F; 9.6.0-X was the first time they were officially used, so this is not a breaking change (there is no content that would use the old versions of those keys).

|  [[9.6.0-24|9.6.0-X]]'s [[FIRM#New_3DS_FIRM|arm9loader]] changed the contents of keyslots 0x19-0x1F; 9.6.0-X was the first time they were officially used, so this is not a breaking change (there is no content that would use the old versions of those keys).

{| class="wikitable" border="1"

{| class="wikitable" border="1"

|-

|-

!  OFFSET

!  Offset

!  SIZE

!  Size

!  DESCRIPTION

!  Description

|-

|-

|  0x000

|  0x000

|  0x180

|  0x180

|  4

|  4

|  Extended header size

|  Extended header size, in bytes

|-

|-

|  0x184

|  0x184

|  RomFS superblock SHA-256 hash - (SHA-256 hash, starting at 0x0 of the RomFS over the number of media units specified in the RomFS hash region size)

|  RomFS superblock SHA-256 hash - (SHA-256 hash, starting at 0x0 of the RomFS over the number of media units specified in the RomFS hash region size)

|}

|}

=== NCCH Flags ===

=== NCCH Flags ===

  009E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................

  009E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................

  009F0 00 03 00 00 00 00 00 00 00 00 00 00 00 00 00 02 . .............

  009F0 00 03 00 00 00 00 00 00 00 00 00 00 00 00 00 02 . .............

== Tools ==

== Tools ==

[https://github.com/3dshax/ctr/tree/master/ctrtool ctrtool] - (CMD)(Windows/Linux) Parsing and decrypting(debug only) NCCH files

[https://github.com/profi200/Project_CTR/tree/master/ctrtool ctrtool] - (CMD)(Windows/Linux) Parsing and decrypting (debug only) NCCH files

 

[[3DSExplorer]] - (GUI)(Windows Only) Parsing NCCH files