nxdumptool/include/core/gamecard.h

/*
 * gamecard.h
 *
 * Copyright (c) 2020-2024, DarkMatterCore <pabloacurielz@gmail.com>.
 *
 * This file is part of nxdumptool (https://github.com/DarkMatterCore/nxdumptool).
 *
 * nxdumptool is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * nxdumptool is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

#pragma once

#ifndef __GAMECARD_H__
#define __GAMECARD_H__

#include "fs_ext.h"
#include "hfs.h"

#ifdef __cplusplus
extern "C" {
#endif

#define GAMECARD_HEAD_MAGIC         0x48454144                      /* "HEAD". */

#define GAMECARD_PAGE_SIZE          0x200
#define GAMECARD_PAGE_OFFSET(x)     ((u64)(x) * GAMECARD_PAGE_SIZE)

#define GAMECARD_UPDATE_TID         SYSTEM_UPDATE_TID

#define GAMECARD_CERTIFICATE_OFFSET 0x7000

/// Encrypted using AES-128-ECB with the common titlekek generator key (stored in the .rodata segment from the Lotus firmware).
typedef struct {
    union {
        u8 value[0x10];
        struct {
            u8 package_id[0x8]; ///< Matches package_id from GameCardHeader.
            u8 reserved[0x8];   ///< Just zeroes.
        };
    };
} GameCardKeySource;

NXDT_ASSERT(GameCardKeySource, 0x10);

/// Plaintext area. Dumped from FS program memory.
typedef struct {
    GameCardKeySource key_source;
    u8 encrypted_titlekey[0x10];    ///< Encrypted using AES-128-CCM with the decrypted key_source and the nonce from this section.
    u8 mac[0x10];                   ///< Used to verify the validity of the decrypted titlekey.
    u8 nonce[0xC];                  ///< Used as the IV to decrypt encrypted_titlekey using AES-128-CCM.
    u8 reserved[0x1C4];
} GameCardInitialData;

NXDT_ASSERT(GameCardInitialData, 0x200);

/// Encrypted using AES-128-CTR with the key and IV/counter from the `GameCardTitleKeyAreaEncryption` section. Assumed to be all zeroes in retail gamecards.
typedef struct {
    u8 titlekey[0x10];  ///< Decrypted titlekey from the `GameCardInitialData` section.
    u8 reserved[0xCF0];
} GameCardTitleKeyArea;

NXDT_ASSERT(GameCardTitleKeyArea, 0xD00);

/// Encrypted using RSA-2048-OAEP and a private OAEP key from AuthoringTool. Assumed to be all zeroes in retail gamecards.
typedef struct {
    u8 titlekey_encryption_key[0x10];   ///< Used as the AES-128-CTR key for the `GameCardTitleKeyArea` section. Randomly generated during XCI creation by AuthoringTool.
    u8 titlekey_encryption_iv[0x10];    ///< Used as the AES-128-CTR IV/counter for the `GameCardTitleKeyArea` section. Randomly generated during XCI creation by AuthoringTool.
    u8 reserved[0xE0];
} GameCardTitleKeyAreaEncryption;

NXDT_ASSERT(GameCardTitleKeyAreaEncryption, 0x100);

/// Used to secure communications between the Lotus and the inserted gamecard.
/// Supposedly precedes the gamecard header.
typedef struct {
    GameCardInitialData initial_data;
    GameCardTitleKeyArea titlekey_area;
    GameCardTitleKeyAreaEncryption titlekey_area_encryption;
} GameCardKeyArea;

NXDT_ASSERT(GameCardKeyArea, 0x1000);

/// Plaintext area. Dumped from FS program memory.
/// Overall structure may change with each new LAFW version.
typedef struct {
    u32 asic_security_mode;     ///< Determines how the Lotus ASIC initialised the gamecard security mode. Usually 0xFFFFFFF9.
    u32 asic_status;            ///< Bitmask of the internal gamecard interface status. Usually 0x20000000.
    FsCardId1 card_id1;
    FsCardId2 card_id2;
    u8 card_uid[0x40];
    u8 reserved[0x190];
    u8 asic_session_hash[0x20]; ///< Changes with each gamecard (re)insertion.
} GameCardSpecificData;

NXDT_ASSERT(GameCardSpecificData, 0x200);

/// Plaintext area. Dumped from FS program memory.
/// This struct is returned by Lotus command "ChangeToSecureMode" (0xF). This means it is only available *after* the gamecard secure area has been mounted.
/// A copy of the gamecard header without the RSA-2048 signature and a plaintext GameCardInfo precedes this struct in FS program memory.
typedef struct {
    GameCardSpecificData specific_data;
    FsGameCardCertificate certificate;
    u8 reserved[0x200];
    GameCardInitialData initial_data;
} GameCardSecurityInformation;

NXDT_ASSERT(GameCardSecurityInformation, 0x800);

typedef enum {
    GameCardKekIndex_Version0      = 0,
    GameCardKekIndex_VersionForDev = 1,
    GameCardKekIndex_Count         = 2  ///< Total values supported by this enum.
} GameCardKekIndex;

typedef struct {
    u8 kek_index          : 4;  ///< GameCardKekIndex.
    u8 titlekey_dec_index : 4;
} GameCardKeyIndex;

NXDT_ASSERT(GameCardKeyIndex, 0x1);

typedef enum {
    GameCardRomSize_1GiB  = 0xFA,
    GameCardRomSize_2GiB  = 0xF8,
    GameCardRomSize_4GiB  = 0xF0,
    GameCardRomSize_8GiB  = 0xE0,
    GameCardRomSize_16GiB = 0xE1,
    GameCardRomSize_32GiB = 0xE2
} GameCardRomSize;

typedef enum {
    GameCardFlags_None                             = 0,
    GameCardFlags_AutoBoot                         = BIT(0),
    GameCardFlags_HistoryErase                     = BIT(1),
    GameCardFlags_RepairTool                       = BIT(2),
    GameCardFlags_DifferentRegionCupToTerraDevice  = BIT(3),
    GameCardFlags_DifferentRegionCupToGlobalDevice = BIT(4),
    GameCardFlags_HasCa10Certificate               = BIT(7),
    GameCardFlags_Count                            = 6          ///< Total values supported by this enum.
} GameCardFlags;

typedef enum {
    GameCardSelSec_ForT1 = 1,
    GameCardSelSec_ForT2 = 2,
    GameCardSelSec_Count = 2    ///< Total values supported by this enum.
} GameCardSelSec;

typedef enum {
    GameCardFwVersion_ForDev       = 0,
    GameCardFwVersion_Since100NUP  = 1, ///< upp_version >= 0 (0.0.0-0.0) in GameCardInfo.
    GameCardFwVersion_Since400NUP  = 2, ///< upp_version >= 268435456 (4.0.0-0.0) in GameCardInfo.
    GameCardFwVersion_Since900NUP  = 3, ///< upp_version >= 603979776 (9.0.0-0.0) in GameCardInfo. Seems to be unused.
    GameCardFwVersion_Since1100NUP = 4, ///< upp_version >= 738197504 (11.0.0-0.0) in GameCardInfo.
    GameCardFwVersion_Since1200NUP = 5, ///< upp_version >= 805306368 (12.0.0-0.0) in GameCardInfo.
    GameCardFwVersion_Count        = 6  ///< Total values supported by this enum.
} GameCardFwVersion;

typedef enum {
    GameCardAccCtrl1_25MHz = 0xA10011,
    GameCardAccCtrl1_50MHz = 0xA10010   ///< GameCardRomSize_8GiB or greater.
} GameCardAccCtrl1;

typedef enum {
    GameCardCompatibilityType_Normal = 0,
    GameCardCompatibilityType_Terra  = 1,
    GameCardCompatibilityType_Count  = 2    ///< Total values supported by this enum.
} GameCardCompatibilityType;

/// Encrypted using AES-128-CBC with the XCI header key (found in FS program memory under HOS 9.0.0+) and the IV from `GameCardHeader`.
typedef struct {
    u64 fw_version;         ///< GameCardFwVersion.
    u32 acc_ctrl_1;         ///< GameCardAccCtrl1.
    u32 wait_1_time_read;   ///< Always 0x1388.
    u32 wait_2_time_read;   ///< Always 0.
    u32 wait_1_time_write;  ///< Always 0.
    u32 wait_2_time_write;  ///< Always 0.
    Version fw_mode;        ///< Current SDK version.
    Version upp_version;    ///< Bundled system update version.
    u8 compatibility_type;  ///< GameCardCompatibilityType.
    u8 reserved_1[0x3];
    u64 upp_hash;           ///< Checksum for the update partition. The exact way it's calculated is currently unknown.
    u64 upp_id;             ///< Must match GAMECARD_UPDATE_TID.
    u8 reserved_2[0x38];
} GameCardInfo;

NXDT_ASSERT(GameCardInfo, 0x70);

/// Placed after the `GameCardKeyArea` section.
typedef struct {
    u8 signature[0x100];                            ///< RSA-2048-PSS with SHA-256 signature over the rest of the header.
    u32 magic;                                      ///< "HEAD".
    u32 rom_area_start_page;                        ///< Expressed in GAMECARD_PAGE_SIZE units.
    u32 backup_area_start_page;                     ///< Always 0xFFFFFFFF.
    GameCardKeyIndex key_index;
    u8 rom_size;                                    ///< GameCardRomSize.
    u8 version;                                     ///< Always 0x00.
    u8 flags;                                       ///< GameCardFlags.
    u8 package_id[0x8];                             ///< Used for challenge-response authentication.
    u32 valid_data_end_page;                        ///< Expressed in GAMECARD_PAGE_SIZE units.
    u8 reserved[0x4];
    u8 card_info_iv[AES_128_KEY_SIZE];              ///< AES-128-CBC IV for the CardInfo area (reversed).
    u64 partition_fs_header_address;                ///< Root Hash File System header offset.
    u64 partition_fs_header_size;                   ///< Root Hash File System header size.
    u8 partition_fs_header_hash[SHA256_HASH_SIZE];
    u8 initial_data_hash[SHA256_HASH_SIZE];
    u32 sel_sec;                                    ///< GameCardSelSec.
    u32 sel_t1_key;                                 ///< Always 0x02.
    u32 sel_key;                                    ///< Always 0x00.
    u32 lim_area_page;                              ///< Expressed in GAMECARD_PAGE_SIZE units.
    GameCardInfo card_info;
} GameCardHeader;

NXDT_ASSERT(GameCardHeader, 0x200);

typedef enum {
    GameCardStatus_NotInserted                     = 0, ///< No gamecard is inserted.
    GameCardStatus_Processing                      = 1, ///< A gamecard has been inserted and it's being processed.
    GameCardStatus_NoGameCardPatchEnabled          = 2, ///< A gamecard has been inserted, but the running CFW enabled the "nogc" patch at boot.
                                                        ///< This triggers an error whenever fsDeviceOperatorGetGameCardHandle is called. Nothing at all can be done with the inserted gamecard.
    GameCardStatus_LotusAsicFirmwareUpdateRequired = 3, ///< A gamecard has been inserted, but a LAFW update is needed before being able to read the secure storage area.
                                                        ///< Operations on the normal storage area are still possible, though.
    GameCardStatus_InsertedAndInfoNotLoaded        = 4, ///< A gamecard has been inserted, but an unexpected error unrelated to both "nogc" patch and LAFW version occurred.
    GameCardStatus_InsertedAndInfoLoaded           = 5, ///< A gamecard has been inserted and all required information could be successfully retrieved from it.
    GameCardStatus_Count                           = 6  ///< Total values supported by this enum.
} GameCardStatus;

typedef enum {
    LotusAsicFirmwareType_ReadFw    = 0xFF,
    LotusAsicFirmwareType_ReadDevFw = 0xFFFF,
    LotusAsicFirmwareType_WriterFw  = 0xFFFFFF,
    LotusAsicFirmwareType_RmaFw     = 0xFFFFFFFF
} LotusAsicFirmwareType;

typedef enum {
    LotusAsicDeviceType_Test     = 0,
    LotusAsicDeviceType_Dev      = 1,
    LotusAsicDeviceType_Prod     = 2,
    LotusAsicDeviceType_Prod2Dev = 3,
    LotusAsicDeviceType_Count    = 4    ///< Total values supported by this enum.
} LotusAsicDeviceType;

/// Plaintext Lotus ASIC firmware (LAFW) blob. Dumped from FS program memory.
typedef struct {
    u8 signature[0x100];
    u32 magic;                      ///< "LAFW".
    u32 fw_type;                    ///< LotusAsicFirmwareType.
    u8 reserved_1[0x8];
    struct {
        u64 fw_version  : 62;       ///< Stored using a bitmask.
        u64 device_type : 2;        ///< LotusAsicDeviceType.
    };
    u32 data_size;
    u8 reserved_2[0x4];
    u8 data_iv[AES_128_KEY_SIZE];
    char placeholder_str[0x10];     ///< "IDIDIDIDIDIDIDID".
    u8 reserved_3[0x40];
    u8 data[0x7680];
} LotusAsicFirmwareBlob;

NXDT_ASSERT(LotusAsicFirmwareBlob, 0x7800);

/// Initializes data needed to access raw gamecard storage areas.
/// Also spans a background thread to automatically detect gamecard status changes and to cache data from the inserted gamecard.
bool gamecardInitialize(void);

/// Deinitializes data generated by gamecardInitialize().
/// This includes destroying the background gamecard detection thread and freeing all cached gamecard data.
void gamecardExit(void);

/// Returns a user-mode gamecard status change event that can be used to wait for status changes on other threads.
/// If the gamecard interface hasn't been initialized, this returns NULL.
UEvent *gamecardGetStatusChangeUserEvent(void);

/// Returns the current GameCardStatus value.
u8 gamecardGetStatus(void);

/// Fills the provided GameCardSecurityInformation pointer.
/// This area can't be read using gamecardReadStorage().
bool gamecardGetSecurityInformation(GameCardSecurityInformation *out);

/// Fills the provided FsGameCardIdSet pointer.
/// This area can't be read using gamecardReadStorage().
bool gamecardGetCardIdSet(FsGameCardIdSet *out);

/// Fills the provided pointers with LAFW blob data from FS program memory.
/// 'out_lafw_blob' or 'out_lafw_version' may be set to NULL, but at least one of them must be a valid pointer.
bool gamecardGetLotusAsicFirmwareBlob(LotusAsicFirmwareBlob *out_lafw_blob, u64 *out_lafw_version);

/// Used to read raw data from the inserted gamecard. Supports unaligned reads.
/// All required handles, changes between normal <-> secure storage areas and proper offset calculations are managed internally.
/// 'offset' + 'read_size' must not exceed the value returned by gamecardGetTotalSize().
bool gamecardReadStorage(void *out, u64 read_size, u64 offset);

/// Fills the provided GameCardHeader pointer.
/// This area can also be read using gamecardReadStorage(), starting at offset 0.
bool gamecardGetHeader(GameCardHeader *out);

/// Fills the provided GameCardInfo pointer.
bool gamecardGetPlaintextCardInfoArea(GameCardInfo *out);

/// Fills the provided FsGameCardCertificate pointer.
/// This area can also be read using gamecardReadStorage(), starting at GAMECARD_CERTIFICATE_OFFSET.
bool gamecardGetCertificate(FsGameCardCertificate *out);

/// Fills the provided u64 pointer with the total gamecard size, which is the size taken by both Normal and Secure storage areas.
bool gamecardGetTotalSize(u64 *out);

/// Fills the provided u64 pointer with the trimmed gamecard size, which is the same as the size returned by gamecardGetTotalSize() but using the trimmed Secure storage area size.
bool gamecardGetTrimmedSize(u64 *out);

/// Fills the provided u64 pointer with the gamecard ROM capacity, based on the GameCardRomSize value from the header. Not the same as gamecardGetTotalSize().
bool gamecardGetRomCapacity(u64 *out);

/// Fills the provided Version pointer with the bundled firmware update version in the inserted gamecard.
bool gamecardGetBundledFirmwareUpdateVersion(Version *out);

/// Fills the provided HashFileSystemContext pointer using information from the requested Hash FS partition.
/// Hash FS functions can be used on the retrieved HashFileSystemContext. hfsFreeContext() must be used to free the underlying data from the filled context.
bool gamecardGetHashFileSystemContext(u8 hfs_partition_type, HashFileSystemContext *out);

/// One-shot function to retrieve meaningful information from a Hash FS entry by name without using gamecardGetHashFileSystemContext() + Hash FS functions.
/// 'out_offset' or 'out_size' may be set to NULL, but at least one of them must be a valid pointer. The returned offset is always relative to the start of the gamecard image.
/// If you need to get entry information by index, just retrieve the Hash FS context for the target partition and use Hash FS functions on it.
bool gamecardGetHashFileSystemEntryInfoByName(u8 hfs_partition_type, const char *entry_name, u64 *out_offset, u64 *out_size);

/// Takes a GameCardFwVersion value. Returns a pointer to a string that represents the minimum HOS version that matches the provided LAFW version.
/// Returns NULL if the provided value is out of range.
const char *gamecardGetRequiredHosVersionString(u64 fw_version);

/// Takes a GameCardCompatibilityType value. Returns a pointer to a string that represents the provided compatibility type.
/// Returns NULL if the provided value is out of range.
const char *gamecardGetCompatibilityTypeString(u8 compatibility_type);

/// Takes a LotusAsicFirmwareType value. Returns a pointer to a string that represents the provided LAFW type.
/// Returns NULL if the provided value is invalid.
const char *gamecardGetLafwTypeString(u32 fw_type);

/// Takes a LotusAsicDeviceType value. Returns a pointer to a string that represents the provided LAFW device type.
/// Returns NULL if the provided value is out of range.
const char *gamecardGetLafwDeviceTypeString(u64 device_type);

#ifdef __cplusplus
}
#endif

#endif /* __GAMECARD_H__ */