ctrsigcheck

README

ctrsigcheck

Parse and verify various file formats used by the Nintendo 3DS, also known as CTR.

This repository contains both a CLI and a Golang library.

Rationale

The main goal is to check both integrity and authenticity of those files before installing them.

The integrity is established by verifying the file structure and embedded SHA-256 hashes.

While not mandatory, the authenticity can also be established thanks to Nintendo signatures. Those digital signatures can be verified using public Nintendo certificates, but cannot be generated without private keys that are only known by Nintendo.

CLI

Installation

The command-line tool can be found precompiled in the releases page.

Alternatively, it can be built and installed from source:

go get github.com/connesc/ctrsigcheck/cmd/ctrsigcheck

An AUR package is also available for Arch Linux users: ctrsigcheck-bin.

Usage

Parse and verify various file formats used by the Nintendo 3DS, also known as CTR

Usage:
  ctrsigcheck [command]

Available Commands:
  cia         Check CIA files
  help        Help about any command
  ticket      Check ticket files
  tmd         Check TMD files

Flags:
  -h, --help   help for ctrsigcheck

Use "ctrsigcheck [command] --help" for more information about a command.

Golang library

Check the go.dev reference.

License

ISC License

Documentation

Overview

Package ctrsigcheck allows to parse and verify various file formats used by the Nintendo 3DS, also known as CTR.

The main goal is to check both integrity and authenticity of those files before installing them. The integrity is established by verifying the file structure and embedded SHA-256 hashes. While not mandatory, the authenticity can also be established thanks to Nintendo signatures. Those digital signatures can be verified using public Nintendo certificates, but cannot be generated without private keys that are only known by Nintendo.

This package comes with a CLI. You can install it like this:

go get github.com/connesc/ctrsigcheck/cmd/ctrsigcheck

Index

• Variables
• func DecodeIconImage(src []byte, width int) (image.Image, error)
• type CIA
  • func CheckCIA(input io.Reader) (*CIA, error)
• type CIAContent
• type CIAContentNCCH
• type CIATMD
• type CIATicket
• type Certificate
• type CertificateSet
• type ExeFS
  • func ParseExeFS(input io.Reader) (*ExeFS, error)
• type Hex
  • func (h Hex) MarshalText() ([]byte, error)
  • func (h Hex) String() string
• type Hex16
  • func (h Hex16) MarshalText() ([]byte, error)
  • func (h Hex16) String() string
• type Hex32
  • func (h Hex32) MarshalText() ([]byte, error)
  • func (h Hex32) String() string
• type Hex64
  • func (h Hex64) MarshalText() ([]byte, error)
  • func (h Hex64) String() string
• type Hex8
  • func (h Hex8) MarshalText() ([]byte, error)
  • func (h Hex8) String() string
• type NCCH
  • func ParseNCCH(input io.Reader) (*NCCH, error)
• type SMDH
  • func ParseSMDH(input io.Reader) (*SMDH, error)
• type SMDHGraphics
• type SMDHTitle
• type TMD
  • func CheckTMD(input io.Reader) (*TMD, error)
• type TMDContent
• type Ticket
  • func CheckTicket(input io.Reader) (*Ticket, error)
• type TitleKey

Variables

var Certs struct {
	Retail CertificateSet
	Debug  CertificateSet
}

Certs contains the retail and debug certificates from Nintendo.

Functions

func DecodeIconImage

func DecodeIconImage(src []byte, width int) (image.Image, error)

DecodeIconImage as found in a SMDH file.

Types

type CIA

type CIA struct {
	Legit    bool
	Complete bool
	TitleID  Hex64
	Ticket   CIATicket
	TMD      CIATMD
	Contents []CIAContent
	Icon     *SMDH
	Meta     bool
}

CIA describes a CIA file.

func CheckCIA

func CheckCIA(input io.Reader) (*CIA, error)

CheckCIA reads the given CIA file and verifies its content.

Many integrity checks are performed, including but not limited to SHA-256 hashes. If any problem is detected, an error is immediately returned. Otherwise, a summary of the CIA file is returned.

Nintendo signatures are not required to be valid. Their status are made available to the caller through the Legit booleans.

A CIA file is considered "legit" if both its ticket and its TMD are "legit". Since the TMD contains the hashes of content segments, a "legit" TMD also guarantees a "legit" content. A "legit" ticket means that content is legitimately owned, either personnally (e.g. game or update downloaded from eShop) or not (e.g. preinstalled game or system title).

type CIAContent

type CIAContent struct {
	Missing bool
	TMDContent
	NCCH *CIAContentNCCH
}

CIAContent describes a content section embedded in a CIA file.

type CIAContentNCCH

type CIAContentNCCH struct {
	Encrypted bool
}

CIAContentNCCH describes the NCCH structure of a content section embedded in a CIA file.

type CIATMD

type CIATMD struct {
	Legit        bool
	Original     bool
	TitleVersion uint16
}

CIATMD describes the TMD embedded in a CIA file.

type CIATicket

type CIATicket struct {
	Legit     bool
	TicketID  Hex64
	ConsoleID Hex32
	TitleKey  TitleKey
}

CIATicket describes the ticket embedded in a CIA file.

type Certificate

type Certificate struct {
	Name      string
	PublicKey rsa.PublicKey
	Raw       []byte
}

Certificate used to verify digital signatures.

type CertificateSet

type CertificateSet struct {
	CA, Ticket, TMD Certificate
}

CertificateSet used to verify digital signatures of tickets and TMDs.

type ExeFS

type ExeFS struct {
	Icon *SMDH
}

ExeFS describes the result of ExeFS parsing.

func ParseExeFS

func ParseExeFS(input io.Reader) (*ExeFS, error)

ParseExeFS extracts some information from the given ExeFS file.

No integrity checks are performed.

type Hex

type Hex []byte

Hex wraps a []byte so that it encodes to hexadecimal.

func (Hex) MarshalText

func (h Hex) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, also used for JSON encoding.

func (Hex) String

func (h Hex) String() string

type Hex16

type Hex16 uint16

Hex16 wraps an uint16 so that it encodes to hexadecimal.

func (Hex16) MarshalText

func (h Hex16) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, also used for JSON encoding.

func (Hex16) String

func (h Hex16) String() string

type Hex32

type Hex32 uint32

Hex32 wraps an uint32 so that it encodes to hexadecimal.

func (Hex32) MarshalText

func (h Hex32) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, also used for JSON encoding.

func (Hex32) String

func (h Hex32) String() string

type Hex64

type Hex64 uint64

Hex64 wraps an uint64 so that it encodes to hexadecimal.

func (Hex64) MarshalText

func (h Hex64) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, also used for JSON encoding.

func (Hex64) String

func (h Hex64) String() string

type Hex8

type Hex8 uint8

Hex8 wraps an uint8 so that it encodes to hexadecimal.

func (Hex8) MarshalText

func (h Hex8) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler, also used for JSON encoding.

func (Hex8) String

func (h Hex8) String() string

type NCCH

type NCCH struct {
	PartitionID Hex64
	ProgramID   Hex64
	Encrypted   bool
	ExeFS       *ExeFS
}

NCCH describes the result of NCCH parsing.

func ParseNCCH

func ParseNCCH(input io.Reader) (*NCCH, error)

ParseNCCH extracts some information from the given NCCH file.

No integrity checks are performed.

type SMDH

type SMDH struct {
	Title    SMDHTitle
	Regions  []string
	Graphics SMDHGraphics
}

SMDH describes the result of SMDH parsing.

func ParseSMDH

func ParseSMDH(input io.Reader) (*SMDH, error)

ParseSMDH extracts some content from the given SMDH file.

type SMDHGraphics

type SMDHGraphics struct {
	Small []byte
	Large []byte
}

SMDHGraphics contains the PNG-encoded icons embedded in a SMDH file.

type SMDHTitle

type SMDHTitle struct {
	ShortDescription string
	LongDescription  string
	Publisher        string
}

SMDHTitle describes a title section embedded in a SMDH file.

type TMD

type TMD struct {
	Legit        bool
	Original     bool
	TitleID      Hex64
	TitleVersion uint16
	Contents     []TMDContent
	CertsTrailer bool
}

TMD describes a TMD structure.

func CheckTMD

func CheckTMD(input io.Reader) (*TMD, error)

CheckTMD reads the given TMD file and verifies its content.

It may be followed by a certificate chain. This notably happens for files downloaded from Nintendo's CDN. If a certificate chain is found, it is checked against expected content.

A TMD is considered "legit" if its digital signature is properly verified. Unlike other checks, signature checks don't produce errors, but instead expose a Legit boolean to the caller.

type TMDContent

type TMDContent struct {
	ID        Hex32
	Index     Hex16
	Type      Hex16
	Size      uint64
	Hash      Hex
	Encrypted bool
	Optional  bool
}

TMDContent describes a content record in a TMD.

type Ticket

type Ticket struct {
	Legit        bool
	TicketID     Hex64
	ConsoleID    Hex32
	TitleID      Hex64
	TitleKey     TitleKey
	CertsTrailer bool
}

Ticket describes the content of a ticket file.

func CheckTicket

func CheckTicket(input io.Reader) (*Ticket, error)

CheckTicket reads the given ticket file and verifies its content.

It may be followed by a certificate chain. This notably happens for files downloaded from Nintendo's CDN. If a certificate chain is found, it is checked against expected content.

A ticket is considered "legit" if its digital signature is properly verified. Unlike other checks, signature checks don't produce errors, but instead expose a Legit boolean to the caller.

type TitleKey

type TitleKey struct {
	Encrypted Hex
	Decrypted Hex
}

TitleKey describes the title key embedded in ticket.