在 7-Zip 26.04 基础上加入对任天堂 3DS / New Nintendo 3DS 容器格式的只读
挂载与解包支持，把 GodMode9 / ctrtool 的解包能力移植为 7-Zip 的一个 archive
handler（N3dsHandler）。代码中不包含任何硬编码密钥——所有密钥由用户从
自己的实机提取后放入与 7z.dll 同目录的 keystone\ctraes_retail\ 与
keystone\ctraes_dev\ 文件夹；目录位置可在 keystone.ini 中自定义。
- 版本：
26.04-CTR03 - 构建目标：Windows x64（
7z.dll/7z.exe/7zFM.exe/7zG.exe/7-zip.dll） - 许可：见 许可 一节
| 状态 | 说明 |
|---|---|
| ✅ 已实现 | 打开并解密下列容器，7zFM / 7z 可浏览、提取 |
| ◐ 部分实现 | 依赖外置密钥；部分加密类型/样本未覆盖 |
| ❌ 未实现 | 未列入本次目标的写入 / 加密导出 / NAND 整卡 |
- 容器识别与挂载：
.3ds.cci.3dz.csu.ncch.cxi.cfa.cia.app.firm.cnt.bin.romfs.exefs.tmd - NCSD（
.3ds/.cci/.3dz/.csu）：解析分区表，定位各分区 NCCH - NCCH（
.cxi/.cfa/.ncch）：展开 ExeFS 与 RomFS- ExeFS：
.codebannericonlogoresources\… - RomFS：完整目录树（含子目录、长文件名 UTF-16BE）
- ExeFS：
- 独立明文段直开：单独抽出的明文
exefs.bin/romfs.bin（或.exefs/.romfs）可直接打开浏览抽取，不需要任何密钥或配套头文件 - CIA：
certtickettmdContent_*.cximeta完整展开- 从 ticket 用 common key 解密 title key
- 加密 content 用 title key 做 AES-CBC 解密读取
- NCCH 数据区 AES-CTR 解密：
slot0x2C/slot0x18/0x1B/0x25- keyscrambler（3DS 硬件密钥生成器，大端字节序）
- Seed 加密 RomFS：读取
seeddb.bin（SeedInfo 格式）派生 seed keyY - Contents.cnt / SNAKE update：CSU 内嵌与单独抽出的
Contents.cnt均可识别； 展开得到的.cia收进专用Contents/子目录，两种场景都按 16 位补零<titleid>.cia命名（独立抽出时从 ticket 段 ticket+0x1DC 读明文 title id， 不依赖兄弟 CupList）；修复了运行时头部越界导致的错误展开。 - 密钥外置（零硬编码），默认目录（相对
7z.dll所在目录）：keystone\ctraes_retail\（零售机）keystone\ctraes_dev\（开发机）- 每个文件为文本格式：
KeyName=<32 位 hex> - 发布包在
7z.dll同目录附带keystone.ini模板（留空=默认），键名为RetailCTRAESKeyDir=/DevCTRAESKeyDir=；目录位置可编辑该文件，也可在7zFM.exe的「选项 → 密钥库（Keystone）」页里浏览指定，每行带「打开文件夹」 按钮（见 docs/KEYS.md）
- dev / retail 自动判定：对 NCCH 数据区用候选 keyX 试解 ExeFS 头， 能解出者选中并记住单元类型
- 开发机 CTR SystemUpdater
.csu全链解密：ExeFS + RomFS 全部展开 - 本机 NAND 备份镜像挂载：打开自己机器的
nand.bin，从keystone\ctrdevice\<SN>\设备档案（boot9 + OTP + NAND CID）在本机派生密钥， 自动匹配设备并流式解密列出 TWL（slot0x03，DSi keyscrambler）、CTRNAND （Old slot0x04 / New slot0x05）、Firm0/Firm1（slot0x06）、AGB_Save（slot0x07）。 机器独有材料全部留在本地，程序不落盘任何派生密钥（见 docs/NAND.md）。 未建设备档案时也可直接把 boot9/OTP/nand_cid 放在 nand.bin 同目录：7zFM 弹窗询问 零售/开发与 Old/New（开发为 CTR/SNAKE），命令行用-unit/-type/-slot指定。
- 密钥必须外置：程序启动时若缺少密钥目录（默认
keystone\ctraes_retail\/keystone\ctraes_dev\）或对应密钥，加密内容无法解密（这是设计，见 密钥）。 - CDN 散 content / TMD（元数据浏览）：可打开 NUS 直抓的
tmd.<n>，解析并 列出 title id、版本、content 数量与各 content 大小/索引（Contents/目录）。 CDN content 外层为 TitleKey-AES-CBC，必须配合 ticket（.tik/.cetk）才能解密； 仅有 TMD 时只做元数据展示，密文不解密（ticket 自动解密位已预留）。 - DSiWare（TWL SRL /
.nds）未实现：00048xxx 标题走 DSi 固定密钥与独立 SRL 格式，不在本版范围。 - NAND TWL 分区（slot0x03）已解密为整段虚拟镜像：由加密 OTP 前 8 字节 + 固定 DSi KeyY + nand_cid 经 DSi keyscrambler 派生，无需额外实机导出；但解出的 twln（FAT16）/ twlp（FAT12）内部目录遍历与 DSiWare title 自身加密层尚未展开。 NAND 设备档案（boot9/OTP/NAND CID）为机器特有，需自备，见 docs/NAND.md。
- 个别异常 header 的 ROM 可能无法解密，属样本本身问题。
- 密钥提取脚本
gm9tools\DumpKeysCTR.lua需在实机上运行（无法在此验证），且 需要 GodMode9 v2.2.0（2025-03-22）或更新——Lua 支持是该版本才加入的， v2.1.1 及更早版本没有 Lua 引擎。旧版请改用发布包自带的keystone\或gm9tools\aeskeys2ctr转换路径。
- 容器写入 / 重新加密 / 导出。
- NAND 整卡写回；TWL 分区内部 twln/twlp 目录遍历与 DSiWare 加密层展开。
- 从你的实机提取密钥（见 docs/EXTRACT_KEYS.md），
放入
7z.dll同目录的keystone\ctraes_retail\/keystone\ctraes_dev\（目录位置可在keystone.ini或「选项 → 密钥库（Keystone）」中改）。 - 将
seeddb.bin（3ds\seeddb.bin，零售机）放在与7z.dll同目录。 - 用
7zFM.exe或7z.exe打开.cia/.csu/.3ds/.cci等文件。 - （可选，NAND 备份）把设备档案放进
keystone\ctrdevice\<SN>\后即可直接打开 本机nand.bin，见 docs/NAND.md。
详细说明见 docs/USAGE.md、docs/KEYS.md、 docs/EXTRACT_KEYS.md、docs/NAND.md、 docs/BUILD.md。
.
├── CPP/7zip/Archive/N3dsHandler.cpp # 3DS 容器 archive handler（本项目核心）
├── Lang/ # 多语言包（基于官方语言包，已并入改名/署名串）
├── docs/ # 使用、密钥、提取、构建文档
├── gm9tools/ # GM9 实机密钥提取脚本与转换工具
├── .github/workflows/build.yml # GitHub Actions 云编译
└── ...
本项目移植与参考了以下公开仓库的能力、格式规范与资源。其中代码均为本项目 独立实现（按公开的 3DS 格式文档编写），仅在能力范围与格式规范上参考下列项目：
| 仓库 | 用途 | 许可 |
|---|---|---|
| d0k3/GodMode9 | 3DS 容器挂载/解密的能力参考（格式规范，代码独立实现） | GPL-3.0 |
| 3DSGuy/Project_CTR (ctrtool) | 文件属性对话框的技术信息字段参考 | MIT |
| ihaveamac/3DS-rom-tools | seeddb.bin 的获取与格式来源 |
MIT |
| redbooth/free-file-icons | 图标模板资源（已并入 Archive\Icons） |
MIT |
| toiry921/CupTheCnt | Contents.cnt 格式的参考（该仓库无开源协议，仅作格式参考，未引用其代码） | 无协议 |
完整的第三方组件、许可与分发义务清单见 THIRD_PARTY.md。
密钥合规说明：本仓库不附带任何密钥材料。解密所需的 AES 密钥可从
已公开的 3DS 研究材料中获得（例如公开流传的 keydata 集合），或由用户
从自己的实机提取（见 docs/EXTRACT_KEYS.md 与
gm9tools）。各机器唯一、且不宜公开分发的密钥（movable.sed、OTP、console-unique、
以及 NAND 设备档案 keystone\ctrdevice\ 里的 boot9/OTP/NAND CID）不会随仓库
或 Release 分发，必须由用户自行提取并只保存在本地。
Rele
823B
ase 包仅附带已在公开研究材料中广泛流传、无争议的固定 AES 密钥。
本项目在 Windows x64 上使用 7-Zip 自带的 makefile 构建（Visual Studio Build
Tools，无需改动即可编译出 7z.dll / 7z.exe / 7zFM.exe 等）。完整步骤、
工具链版本与常见问题见 docs/BUILD.md。
关键点：
- 安装 Visual Studio 2022 Build Tools（含 C++ 工具集与 x64 编译环境）。
- 在仓库根目录按
docs/BUILD.md调用makefile构建 x64 目标。 - 编译产物在对应
x64\目录；安装器（C\Util\7zipInstall）与卸载器 （C\Util\7zipUninstall）也可一并编译。 - 运行前把密钥放入
7z.dll同目录（见上文“密钥合规说明”与docs/KEYS.md）。
仓库内已配置 GitHub Actions，推到 GitHub 即可自动云编译并产出构建产物。
本项目基于以下开源项目：
- 原始项目： https://github.com/ip7z/7zip
- 作者： Igor Pavlov
- 许可证： GNU LGPL-2.1（附带 unRAR license restriction）
本项目主体代码继承 7-Zip 的许可证要求。
CPP/7zip/Archive/N3dsHandler.cpp 等由本项目新增或修改的代码：
- 许可证：GNU LGPL-2.1
- 版权所有： 7-Zip 原作者 Igor Pavlov 与本项目贡献者
- 图标资源：
基于
redbooth/free-file-icons的 MIT 许可资源修改。 - 多语言包
Lang/： 基于 7-Zip 官方语言包（版权归 Igor Pavlov 与各语种译者，随 7-Zip LGPL 分发）， 本项目在其上并入了软件改名与“Adnini983 AI 创作”署名串，未改动其余译文。 - 其他第三方参考项目： 请见“参考仓库与资源”章节。
完整许可证文本见仓库根目录 LICENSE.md 以及 7-Zip 原始源码中的 DOC/License.txt。
本项目基于官方 7-Zip 源码修改而来。
- 原始项目：7-Zip
- 原作者：Igor Pavlov
- 官方网站：https://www.7-zip.org/
- 原始 GitHub 仓库：https://github.com/ip7z/7zip
本仓库并非 7-Zip 官方项目，而是基于 7-Zip 源码进行二次开发的个人修改版本。
仓库与发布包不得含有下列内容（CI 与打包脚本会强制检查）：
| 禁止项 | 说明 |
|---|---|
| 主机序列号 | 文档/脚本中一律写 <序列号> |
| 密钥明文 | 文档中写 <32 位十六进制>；脚本内嵌密钥必须混淆（XOR + base64） |
| 每台机器特有的数据 | boot9.bin、otp.mem、otp_dec.mem、nand_cid.mem、movable.sed、ctrindex.ini、keystone\ctrdevice\、keystone.cache |
松散 .key 文件 |
只在发布包里允许（内置的公开 AES 子集，handler 直接读）；仓库内不得出现 |
- 仓库侧：
scripts\check_no_secrets.ps1（CI 每次构建前执行，命中即失败） - 发布侧：
scripts\check_release_package.ps1 -SevenZip 7z.exe -Package <包>（打包后审计； 默认接受公开.key子集，加-ForbidLooseKeys可要求完全无.key）
- 代码与文档生成辅助：部分代码、文档、图标设计和构建脚本由 AI 工具（豆包 / Doubao、DeepSeek）辅助生成。
- 用户贡献：功能需求、测试环境、实机验证以及项目方向由用户提供。
- 感谢 Igor Pavlov 与 7-Zip 社区、GodMode9 项目、 ctrtool、3DS-rom-tools、 free-file-icons 等开源项目。