• 开发工具
• 逆向工程

导读

mbedtls/README.md 是 hactool 仓库内嵌的 mbed TLS 加密库的官方构建与配置文档。hactool 作为一个 Nintendo Switch 文件格式（NCA、XCI、PFS0、RomFS 等）查看、解密与提取工具，其全部 AES、SHA-256、HMAC、RSA 与 CMAC 密码学能力都来自这份随仓库携带的 mbed TLS 2.6.1 源码树。读完本文，你将掌握 hactool 从顶层make到 mbed TLS 内部库依赖的全部构建链路，学会用config.pl脚本裁剪功能开关、用 Make/CMake/Yotta 三种方式编译出libmbedcrypto、libmbedx509、libmbedtls三个库，并了解其自测套件的生成与运行机制。

一、定位：hactool 为什么自带一份 mbed TLS

hactool 顶层 Makefile 的第一行就是include config.mk，其all目标第一步执行$(MAKE) -C mbedtls lib，也就是先在本仓库的mbedtls/目录内编译出三个静态库，再链接出hactool可执行文件。配套的 config.mk.template 中写明了链接参数：

CC = gcc CFLAGS = -O2 -Wall -Wextra -pedantic -std=gnu11 -fPIC LDFLAGS = -lmbedtls -lmbedx509 -lmbedcrypto

链接顺序-lmbedtls -lmbedx509 -lmbedcrypto正是 mbed TLS README 反复强调的依赖方向：libmbedtls依赖libmbedx509与libmbedcrypto，libmbedx509又依赖libmbedcrypto。GNU 链接器对库顺序敏感，如果颠倒顺序就会产生未解析符号错误。

从源码可以清楚看到 hactool 对这三层库的实际使用：

• sha.h 直接#include "mbedtls/md.h"，其hash_type_t枚举直接映射到MBEDTLS_MD_SHA1/MBEDTLS_MD_SHA256；sha.c 中通过mbedtls_md_setup、mbedtls_md_starts、mbedtls_md_hmac_starts完成 SHA-256 摘要与 HMAC 计算；
• aes.h 使用mbedtls_cipher_context_t与mbedtls/cmac.h，负责 NCA 内容解密与密钥派生；
• rsa.c 使用mbedtls_mpi大数运算完成 RSA-2048 签名验证。

本仓库携带的 mbed TLS 版本为2.6.1（见 version.h 中的MBEDTLS_VERSION_STRING）。

二、配置：config.h与scripts/config.pl

mbed TLS 官方宣称"开箱即用"，平台相关的可选项与功能开关全部集中在 include/mbedtls/config.h（共约 2700 行，内含大量\def文档注释）。该文件可以通过两种方式修改：

1. 手工编辑：直接打开config.h，注释或取消注释#define行；
2. 脚本化修改：使用 scripts/config.pl 进行程序化控制。

config.pl支持四个核心命令（完整用法可用--help查看）：

config.pl也接受-f <file>指定配置文件路径（默认include/mbedtls/config.h），且允许从项目根目录或scripts/目录运行。这里要特别留意full模式的保留名单，其中MBEDTLS_TEST_NULL_ENTROPY是最危险的一项：它表示"无任何熵源"，仅供开发测试使用。Makefile 的post_build目标与顶层 CMakeLists.txt 都会在构建时调用config.pl get MBEDTLS_TEST_NULL_ENTROPY做检查，一旦命中就会打印醒目的警告横幅：

**** WARNING! MBEDTLS_TEST_NULL_ENTROPY defined! **** **** THIS BUILD HAS NO DEFINED ENTROPY SOURCES **** **** AND IS *NOT* SUITABLE FOR PRODUCTION USE ****

CMake 下若检测到该开关且未显式传入-DUNSAFE_BUILD=ON，构建会直接FATAL_ERROR终止。

使用configs/中的非标准配置

仓库 mbedtls/configs/ 提供了一批面向特定使用场景的精简配置，例如config-mini-tls1_1.h（最小化 TLS 1.1）、config-suite-b.h（仅 Suite B 密码套件）、config-no-entropy.h（无熵源）、config-thread.h（线程支持）等。这些文件是config.h的完整替代品，有两种启用方式：

1. 直接替换：把选中的配置复制为include/mbedtls/config.h，注意根据编译器调整其中的#include "mbedtls/check_config.h"一行；
2. 不改文件、只改宏：通过定义MBEDTLS_CONFIG_FILE并调整头文件搜索路径，例如 Make 下：

CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE='<foo.h>'" make

find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} + CFLAGS="-I$PWD/configs -DMBEDTLS_CONFIG_FILE='<foo.h>'" cmake . make

第二种方法同样适用于把自定义配置文件放在 mbed TLS 源码树之外的情形，而且无需改动仓库文件。

三、构建系统总览：四种方式与三个库

README 明确列出了 mbed TLS 版本中活跃的四套构建系统：

• Yotta：mbed OS 16.03 的构建系统，提供极简配置文件，示例与测试可能依赖 mbed OS 特性；
• Make：开发主用系统，功能完整、保持最新；
• CMake：开发主用系统，功能完整、保持最新；
• Microsoft Visual Studio（VS6 与 VS2010）：其余系统应反映 Make/CMake 的全部变更，但新特性不一定自动移植。

Make 与 CMake 都会产出三个库：libmbedcrypto（AES、SHA、RSA、MPI 等纯密码学）、libmbedx509（证书解析与签名）、libmbedtls（TLS/DTLS 协议）。依赖关系为libmbedtls → libmbedx509 → libmbedcrypto，这与上一节 hactool 的链接参数一一对应；另外当用dlopen()动态加载共享库时，必须先加载 libmbedcrypto，再加载 libmbedx509，最后才能加载 libmbedtls。

四、Make 构建：从单库编译到 hactool 全量构建

4.1 基础命令

在mbedtls/目录下：

make # 编译库与全部示例程序 make check # 运行测试（测试需要 Perl 参与生成） make no_test # 跳过测试生成，只编译库与程序 programs/test/selftest # 无 Perl 时可运行的自检程序（小型测试集）

mbed TLS 的 Makefile 刻意只使用最小化的 Make 语法，因为不同平台/不同实现（BSD make、GNU make）对高级特性支持不一，因此个别平台可能需要手动修改 library/Makefile、programs/Makefile 或 tests/Makefile。

4.2 平台与构建变量

例如 debug 构建：make DEBUG=1；共享库构建：make SHARED=1。

4.3 与 hactool 顶层构建的整合

hactool 并不直接在mbedtls/下手工执行上述命令，而是在仓库根目录运行：

cp config.mk.template config.mk # 首次构建前必做 make # 自动进入 mbedtls 编译库，再链接 hactool

顶层 Makefile 会把-D_BSD_SOURCE、-D_POSIX_SOURCE、-D_FILE_OFFSET_BITS=64等宏并入CFLAGS，并把-I ./mbedtls/include与-L ./mbedtls/library分别作为头文件与库目录传入。README 还提示：如果你的make不是 GNU make（如 BSD 变体），应改用gmake；Windows 上推荐 MinGW 环境。

五、CMake 构建：最小步骤与八种构建模式

5.1 基本流程

cmake . make make test # 运行测试

与 Make 一样，测试套件需要 Perl；没有 Perl 时关闭测试：

cmake -DENABLE_TESTING=Off .

关掉测试但保留程序时，仍可运行小型自检：programs/test/selftest。构建共享库版本：

cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On .

顶层 CMakeLists.txt 还暴露了ENABLE_PROGRAMS（默认 ON）、ENABLE_ZLIB_SUPPORT（默认 OFF）、USE_PKCS11_HELPER_LIBRARY（默认 OFF）等选项。

5.2 构建模式（Build Type）

CMake 内置了多套针对 gcc/clang 的构建模式，部分与编译器相关：

切换模式很简单，例如：

cmake -D CMAKE_BUILD_TYPE=Debug .

查看全部可用的 CMake 选项：cmake -LH。注意：CMake 已经运行过一次之后，想更换编译器或编译选项必须清空缓存，例如：

find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} + CC=gcc CFLAGS='-fstack-protector-strong -Wa,--noexecstack' cmake .

这套模式在 hactool 仓库内并未启用（hactool 直接用顶层 Make 构建），但它对希望自行对 mbed TLS 做内存安全审计或覆盖率分析的开发者非常实用。

六、Yotta 与 Visual Studio 构建

6.1 Yotta（mbed OS 场景）

Yotta 是 mbed 开发的包管理器兼构建系统。从 yotta 仓库安装：

yotta install mbedtls yotta build

如果手上是源码副本（例如直接克隆的仓库），需要先在 mbed TLS 根目录运行 yotta/create-module.sh，它会生成yotta/module/目录：

yotta/create-module.sh cd yotta/module yotta build

构建前通常需要先设置 yotta target（除非已在全局设置）。该脚本会把include/mbedtls/*.h与library/*.c复制进模块，并调用scripts/config.pl生成精简的config.h；mbedtls/yotta/data/目录下还包含entropy_hardware_poll.c、target_config.h、module.json与若干 example 程序。对 hactool 而言，Yotta 面向的是 mbed OS 设备端，与本仓库的桌面解密工具定位不同，属于移植/复用参考。

6.2 Visual Studio

仓库的 VS 构建文件面向Visual Studio 2010，位于 visualc/VS2010/。解决方案文件mbedTLS.sln包含构建库与全部程序所需的所有基础项目；tests/下的测试文件不会被编译（它们同样需要 Perl 环境），但programs/test/中的 selftest 程序仍然可用。

七、测试体系：.function + .data 生成机制与集成脚本

mbed TLS 自带完善的测试套件，全部位于 mbedtls/tests/：

• 生成机制：测试最初需要 Perl 生成测试 C 文件（如test_suite_mpi.c）。每个套件由两部分组成——function 文件（如 suites/test_suite_mpi.function，存放测试函数）与data 文件（如 suites/test_suite_mpi.data，存放以参数形式传递给测试函数的用例）。从 tests/Makefile 可以看到，生成出的套件覆盖 AES 各模式、ARC4、Blowfish、Camellia、CCM、CMAC、CTR_DRBG、HMAC_DRBG、ECP/ECDH/ECDSA、GCM、MPI、RSA、PKCS 系列、SSL、X509 解析/写入、SHA 系列等数十个模块。

对于带 Unix shell 且安装了 OpenSSL（可选 GnuTLS）的机器，还有额外的集成脚本：

与 hactool 相关的实际验证手段是：在构建 mbed TLS 后运行programs/test/selftest（selftest.c），它会就地执行内置的算法自检，无需 Perl，可作为链接进 hactool 前的最小健康检查。

八、示例程序：programs/的用法参考

mbedtls/programs/ 按功能分目录收录了大量示例程序：aes/（aescrypt2、crypt_and_hash）、hash/（generic_sum、hello）、pkey/（rsa_genkey、rsa_sign、ecdsa、dh_client/server 等）、random/（gen_entropy、gen_random_ctr_drbg）、ssl/（ssl_client1/2、ssl_server、dtls_client/server、mini_client 等）、test/（selftest、benchmark）、util/（pem2der、strerror）、x509/（cert_app、cert_write、req_app 等）。README 特别提醒：这些程序大多只聚焦单一功能或单一使用场景，复制代码时要留意这一点——这对希望把 mbed TLS 的 AES/SHA 能力复用到其他工具中的开发者尤其重要。

九、移植与贡献注意事项

mbed TLS 可以移植到多种架构、操作系统与平台。做移植前，README 建议先查阅官方知识库中关于"移植到新环境/新 OS"、"外部依赖"、"如何配置"的三篇文章（外部链接不在本文转载范围内，可直接阅读仓库内 config.h 与 library/Makefile 中的平台注释来获得同类信息，例如 MicroBlaze 的-mno-xl-soft-mul、Plan9 的-D_BSD_EXTENSION、SunOS 的-lsocket -lnsl等）。

若向 mbed TLS 上游贡献代码，README 列出了三项硬性要求：所有贡献（无论大小）都需签署贡献者许可协议（CLA）；代码须符合官方编码规范并附带完整测试；提交后经项目团队与社区评审。标准流程是：先查询/讨论 issue → fork 上游仓库（基于 development 分支）→ 编写证明 bug 修复或功能生效的测试 → 提交 Pull Request。作为只读仓库，hactool 内的这份 mbed TLS 用于构建使用，不涉及就地修改。

十、总结：把整套构建链串起来

对 hactool 使用者来说，最常用到的完整链路是：

# 1. 准备 config.mk（首次） cp config.mk.template config.mk # 2. 一键构建：先编译 mbedtls 三个库，再链接 hactool make # 3. （可选）在 mbed TLS 内做功能裁剪，例如 scripts/config.pl unset MBEDTLS_SSL_DTLS_ANTI_REPLAY # 需在 mbedtls/ 目录下执行 make

其中mbedtls/目录内嵌的 mbed TLS 2.6.1 提供了 hactool 所需的全部底层密码学原语——AES 加解密（aes.h → mbedtls cipher/CMAC）、SHA-256 与 HMAC（sha.c → mbedtls MD 层）、RSA-2048 验签（rsa.c → mbedtls MPI）。理解其配置开关、三种构建路径与依赖顺序，既能保证 hactool 顺利编译，也能在需要裁剪体积或做安全审计时灵活调整这份加密底座。

• 开发工具
• 逆向工程