engine - AES engine tools

The engine module provides tools to perform cryptographic operations on Nintendo 3DS data, including emulating keyslots and the key scrambler.

Warning

This page is incomplete.

AES engine

The 3DS uses keyslots in an attempt to obscure the encryption keys used. Each slot consists of X, Y, and normal keys.

Often, one slot contains a fixed key (often X), while the other is a key unique to something such as a game or console (often Y). When key Y is set, both keys are put into a key scrambler, and the result is stored as a normal key. The AES engine would then use the result for encryption. A normal key can also be set directly.

The AES engine only has keyslots 0x0 to 0x3F (0 to 63). Keyslots 0x0 to 0x3 are for DSi-mode software, and use the DSi key scrambler. This module uses keyslots above 0x3F for internal use.

CryptoEngine objects

class pyctr.crypto.engine.CryptoEngine(boot9=None, dev=False, setup_b9_keys=True)[source]

Emulates the AES engine, including keyslots and the key scrambler.

Parameters:

  • boot9 (FilePathOrObject) – Path to a dump of the protected region of the ARM9 BootROM. Defaults to None, which causes it to search a predefined list of paths.

  • dev (bool) – Use devunit keys.

  • setup_b9_keys (bool) – Automatically load keys from boot9. This calls setup_boot9_keys().

create_cbc_cipher(keyslot, iv)[source]

Create an AES-CBC cipher.

Parameters:

  • keyslot (Keyslot) – Keyslot to use.

  • iv (bytes) – Initialization vector.

Returns:

An AES-CBC cipher object.

Return type:

CbcMode

create_ctr_cipher(keyslot, ctr)[source]

Create an AES-CTR cipher.

Parameters:

  • keyslot (Keyslot) – Keyslot to use.

  • ctr (int) – Counter to start with.

Returns:

An AES-CTR cipher object.

Return type:

CtrMode | _TWLCryptoWrapper

create_ecb_cipher(keyslot)[source]

Create an AES-ECB cipher.

Parameters:

keyslot (Keyslot) – Keyslot to use.

Returns:

An AES-ECB cipher object.

Return type:

EcbMode

create_cmac_object(keyslot)[source]

Create a CMAC object.

Parameters:

keyslot (Keyslot) – Keyslot to use.

Returns:

A CMAC object.

Return type:

CMAC

create_ctr_io(keyslot, fh, ctr, closefd=False)[source]

Create an AES-CTR read-write file object with the given keyslot.

Parameters:

  • keyslot (Keyslot) – Keyslot to use.

  • fh (BinaryIO) – File-like object to wrap.

  • ctr (int) – Counter to start with.

  • closefd (bool) – Close underlying file object when closed.

Returns:

A file-like object that does decryption and encryption on the fly.

Return type:

CTRFileIO

create_cbc_io(keyslot, fh, iv, closefd=False)[source]

Create an AES-CBC read-write file object with the given keyslot.

Parameters:

  • keyslot (Keyslot) – Keyslot to use.

  • fh (BinaryIO) – File-like object to wrap.

  • iv (bytes) – Initialization vector.

  • closefd (bool) – Close underlying file object when closed.

Returns:

A file-like object that does decryption and encryption on the fly.

Return type:

CBCFileIO

set_keyslot(xy, keyslot, key, *, update_normal_key=True)[source]

Sets a keyslot.

Parameters:

  • xy (Literal['x', 'y']) – X or Y.

  • keyslot (Keyslot) – Keyslot to set.

  • key (bytes | int) – Key to set it to. If provided as an integer, it is converted to little- or big-endian depending on if the keyslot is <=0x03.

  • update_normal_key (bool) – Update the normal key based on the value of X and Y.

set_normal_key(keyslot, key)[source]

Set a keyslot’s normal key.

Parameters:

  • keyslot (Keyslot) – Keyslot to set.

  • key (bytes) – Key to set it to.

update_normal_keys()[source]

Refresh normal keys. This is only required if set_keyslot() was called with update_normal_key=False.