Mbed-TLS/mbedtls
GitHub: Mbed-TLS/mbedtls
一个开源的轻量级 TLS/DTLS 加密库，为嵌入式系统和物联网设备提供安全通信能力和 X.509 证书处理。
Stars: 6512 | Forks: 2851
# Mbed TLS 自述文件
Mbed TLS 是一个 C 语言库，实现了 X.509 证书处理以及 TLS 和 DTLS 协议。其代码占用空间小，非常适合嵌入式系统。
Mbed TLS 包含 [TF-PSA-Crypto 仓库](https://github.com/Mbed-TLS/TF-PSA-Crypto)，该仓库提供了 [PSA Cryptography API](https://arm-software.github.io/psa-api) 的实现。
## 配置
与 X.509 和 TLS 相关的配置选项位于 `include/mbedtls/mbedtls_config.h`，而加密和平台选项则位于 TF-PSA-Crypto 配置文件 `tf-psa-crypto/include/psa/crypto_config.h` 中。
使用默认的平台选项，Mbed TLS 应该可以在大多数系统上开箱即用地构建。
这些配置文件可以手动编辑，也可以使用 Python 脚本 `scripts/config.py` 以编程方式修改（运行时使用 --help 查看使用说明）。
我们在 `configs/` 目录中提供了一些针对特定用例的非标准配置。您可以在 `configs/README.txt` 中阅读更多相关信息。
## 文档
Mbed TLS 的主要文档可通过 [ReadTheDocs](https://mbed-tls.readthedocs.io/) 获取。
要生成本地 HTML 格式的库文档副本，并根据您的编译时配置进行调整：
1. 确保已安装 [Doxygen](http://www.doxygen.nl/)。
2. 运行 `cmake -B /path/to/build_dir /path/to/mbedtls/source`
3. 运行 `cmake --build /path/to/build_dir --target mbedtls-apidoc`
4. 打开以下主要生成的 HTML 文件之一：
* `apidoc/index.html`
* `apidoc/modules.html` 或 `apidoc/topics.html`
有关其他文档来源，请参阅 [SUPPORT](SUPPORT.md) 文档。
## 编译
我们使用 CMake 来配置和驱动我们的构建过程。构建了三个库：`libtfpsacrypto`、`libmbedx509` 和 `libmbedtls`。请注意，`libmbedtls` 依赖于 `libmbedx509` 和 `libtfpsacrypto`，而 `libmbedx509` 依赖于 `libtfpsacrypto`。因此，某些链接器希望标志按特定顺序排列，例如 GNU 链接器需要 `-lmbedtls -lmbedx509 -ltfpsacrypto`。加密库 `libtfpsacrypto` 也以其旧名称 `libmbedcrypto` 提供。
### 工具版本
要使用提供的 CMake 文件从主分支构建库，您需要以下工具。Mbed TLS 的最低工具版本要求是根据主要 Linux 发行版的最新或倒数第二个（取决于发布周期）长期支持版本中附带的版本设定的，即在撰写本文时：Ubuntu 22.04、RHEL 9 和 SLES 15 SP4。
* CMake 3.20.2 或更高版本。
* CMake 可以生成其构建文件的构建系统，如 Make 或 Ninja。
* C99 工具链（编译器、链接器、归档器）。我们积极测试 GCC 5.4、Clang 3.8、Arm Compiler 6 和 Visual Studio 2017 Compiler。更新的版本应该可以工作。稍旧的版本可能也可以工作。
* Python 3.8 或更高版本，用于生成测试代码。构建开发分支也需要 Python（见下一节）。
* Perl，用于运行测试，以及生成开发分支中的某些源文件。
* Doxygen 1.8.14 或更高版本（如果构建文档；稍旧的版本应该也可以工作）。
### Git 用法
支持的分支（参见 [`BRANCHES.md`](BRANCHES.md)) 使用 [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules))。它们包含两个子模块：[framework](https://github.com/Mbed-TLS/mbedtls-framework) 子模块和 [tf-psa-crypto](https://github.com/Mbed-TLS/TF-PSA-Crypto) 子模块，但 3.6 LTS 分支除外，该分支仅包含 framework 子模块。发布标签也使用 Git 子模块。
在克隆或检出分支或标签后，请运行：
```
git submodule update --init --recursive
```
以便在构建之前初始化和更新子模块。
然而，官方源代码发布压缩包（例如 [mbedtls-4.0.0.tar.bz2](https://github.com/Mbed-TLS/mbedtls/releases/download/mbedtls-4.0.0/mbedtls-4.0.0.tar.bz2)) 包含了子模块的内容。
### 开发分支中生成的源文件
Mbed TLS 的源代码包含一些由脚本自动生成的文件，其内容仅取决于 Mbed TLS 源代码，而不取决于平台或库配置。这些文件不包含在 Mbed TLS 的开发分支中，但生成的文件包含在官方版本中。本节介绍如何在开发分支中生成缺失的文件。
需要以下工具：
* Perl，用于某些库源文件。
* Python 3 和一些 Python 包，用于某些库源文件、示例程序和测试数据。要安装必要的包，请运行：
python3 -m pip install --user -r scripts/basic.requirements.txt
根据您的 Python 安装情况，您可能需要调用 `python` 而不是 `python3`。要在系统范围内或虚拟环境中安装包，请省略 `--user` 选项。
* 主机平台的 C 编译器，用于某些测试数据。
生成与配置无关的文件的脚本将在以下位置查找主机 C 编译器（按优先顺序）：
1. `HOSTCC` 环境变量。如果 `CC` 指向交叉编译器，可以使用此变量。
2. `CC` 环境变量。
3. 当前路径中名为 `cc` 的可执行文件。
注意：如果您安装了多个工具链，建议在生成文件之前将 `CC` 或 `HOSTCC` 设置为预期的主机编译器。
可以使用以下任何方法来生成与配置无关的文件：
* 在非 Windows 系统上，当不进行交叉编译时，CMake 会自动生成所需的文件。
* 运行 `framework/scripts/make_generated_files.py` 以生成所有与配置无关的文件。
### CMake
为了在单独的目录中使用 CMake 构建库（推荐），只需在命令行输入：
```
mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
cmake --build .
```
为了运行测试，请输入：
```
ctest
```
构建测试套件需要 Python。如果您没有安装 Python，可以使用以下命令禁用测试套件：
```
cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
```
要将 CMake 配置为构建共享库，请使用：
```
cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source
```
CMake 提供了许多不同的构建类型。其中大多数适用于 gcc 和 clang，尽管有些是特定于编译器的：
- `Release`。生成默认代码，二进制文件中不包含任何不必要的信息。
- `Debug`。生成调试信息并禁用代码优化。
- `Coverage`。除了调试信息外，还生成代码覆盖率信息。
- `ASan`。使用 AddressSanitizer 检测代码以检查内存错误。（这包括 LeakSanitizer，适用于最新版本的 gcc 和 clang。）（对于最新版本的 clang，此模式还使用 UndefinedSanitizer 检测代码以检查未定义的行为。）
- `ASanDbg`。与 ASan 相同，但速度较慢，带有调试信息和更好的堆栈跟踪。
- `MemSan`。使用 MemorySanitizer 检测代码以检查未初始化的内存读取。
- `MemSanDbg`。与 MemSan 相同，但速度较慢，带有调试信息、更好的堆栈跟踪和起源跟踪。
- `Check`。激活依赖于优化的编译器警告，并将所有警告视为错误。
- `TSan`。使用 ThreadSanitizer 检测代码，以在运行时检测数据竞争和其他与线程相关的并发问题。
- `TSanDbg`。与 TSan 相同，但速度较慢，带有调试信息、更好的堆栈跟踪和起源跟踪。
在 CMake 中切换构建类型很简单。对于调试模式，在命令行输入：
```
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
```
要列出其他可用的 CMake 选项，请使用：
```
cmake -LH
```
请注意，使用 CMake 时，您无法在初次调用 cmake 之后调整编译器或其标志。这意味着 `CC=your_cc make` 和 `make CC=your_cc` 将*不*起作用（`CFLAGS` 和其他变量也是如此）。这些变量需要在首次调用 cmake 时进行调整，例如：
```
CC=your_cc cmake /path/to/mbedtls_source
```
如果您已经调用了 cmake 并想要更改这些设置，则需要使用新设置再次调用 CMake 的配置阶段。
请注意，可以就地构建；但这将覆盖仍用于测试目的的旧版 Makefiles（如果您想防止 `git status` 将它们显示为已修改，请参见 `scripts/tmp_ignore_makefiles.sh`）。为此，从 Mbed TLS 源代码目录中使用：
```
cmake .
cmake --build .
```
如果您之后想要更改 `CC` 或 `CFLAGS`，则需要删除 CMake 缓存。可以使用 GNU find 通过以下命令完成此操作：
```
find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
```
您现在可以进行所需的更改：
```
CC=your_cc cmake .
cmake --build .
```
关于变量，还要注意，如果在调用 cmake 时设置了 CFLAGS，您的 CFLAGS 值不会覆盖 CMake 提供的内容（取决于如上所示的构建模式），而只是附加在其前面。
#### 使用 Mbed TLS
Mbed TLS 提供了一个 CMake 包配置文件，以便在其他 CMake 项目中将其作为依赖项使用。您可以通过以下方式加载其 CMake 目标：
```
find_package(MbedTLS REQUIRED)
```
您可以帮助 CMake 找到该包：
- 通过将变量 `MbedTLS_DIR` 设置为 `${YOUR_MBEDTLS_BUILD_DIR}/cmake`，如 `programs/test/cmake_package/CMakeLists.txt` 中所示，或者
- 通过将 Mbed TLS 安装前缀添加到 `CMAKE_PREFIX_PATH`，如 `programs/test/cmake_package_install/CMakeLists.txt` 中所示。
在成功执行 `find_package(MbedTLS)` 后，可以使用以下导入目标：
- `MbedTLS::tfpsacrypto`，加密库
- `MbedTLS::mbedtls`，TLS 库
- `MbedTLS::mbedx509`，X.509 库
然后，您可以直接通过 `target_link_libraries()` 使用它们：
```
add_executable(xyz)
target_link_libraries(xyz
PUBLIC MbedTLS::mbedtls
MbedTLS::tfpsacrypto
MbedTLS::mbedx509)
```
这会将 Mbed TLS 库链接到您的库或应用程序，并将其包含目录添加到您的目标中（对于 `PUBLIC` 或 `INTERFACE` 链接库，则是传递性的）。
#### Mbed TLS 作为子项目
Mbed TLS 支持作为 CMake 子项目构建。可以从父 CMake 项目使用 `add_subdirectory()` 将 Mbed TLS 作为子项目包含进来。
## 示例程序
我们在 [`programs/`](programs/README.md) 中包含了许多针对不同功能和用途的示例程序。
请注意，这些示例程序的目标是演示库的特定功能，可能需要调整代码才能构建实际的应用程序。
## 测试
Mbed TLS 在 `tests/` 中包含了一套详尽的测试套件，最初需要 Python 来生成测试文件（例如 `test_suite_ssl.c`）。这些文件是从 `function file`（例如 `suites/test_suite_ssl.function`）和 `data file`（例如 `suites/test_suite_ssl.data`）生成的。`function file` 包含测试函数。`data file` 包含测试用例，指定为将传递给测试函数的参数。
对于安装了 Unix shell 和 OpenSSL（以及可选的 GnuTLS）的机器，还提供了额外的测试脚本：
- `tests/ssl-opt.sh` 运行各种 TLS 选项（重新协商、恢复等）的集成测试，并测试这些选项与其他实现的互操作性。
- `tests/compat.sh` 测试每个密码套件与其他实现的互操作性。
- `tests/scripts/depends.py` 在仅启用单个曲线、密钥交换、哈希、密码或 pkalg 的配置中测试构建。
- `tests/scripts/all.sh` 运行上述测试的组合，以及更多测试，并使用各种构建选项（例如 ASan、完整的 `mbedtls_config.h` 等）。
无需手动安装测试所需的所有工具的特定版本，您可以使用我们 CI 系统中的 Docker 镜像，如 [我们的测试基础架构仓库](https://github.com/Mbed-TLS/mbedtls-test/blob/main/README.md#quick-start) 中所述。
## 移植 Mbed TLS
Mbed TLS 可以移植到许多不同的架构、操作系统和平台。在开始移植之前，您可能会发现以下知识库文章很有用：
- [将 Mbed TLS 移植到新环境或操作系统](https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS/)
- [Mbed TLS 依赖哪些外部依赖项？](https://mbed-tls.readthedocs.io/en/latest/kb/development/what-external-dependencies-does-mbedtls-rely-on/)
- [如何配置 Mbed TLS](https://mbed-tls.readthedocs.io/en/latest/kb/compiling-and-building/how-do-i-configure-mbedtls/)
Mbed TLS 大部分是使用可移植的 C99 编写的；然而，它有一些超出标准但大多数现代架构都能满足的平台要求：
- 字节必须是 8 位。
- 全零位必须是空指针的有效表示。
- 有符号整数必须使用二进制补码表示。
- `int` 和 `size_t` 必须至少为 32 位宽。
- 类型 `uint8_t`、`uint16_t`、`uint32_t` 及其有符号等效项必须可用。
- 不支持混合字节序平台。
- SIZE_MAX 必须至少与 INT_MAX 和 UINT_MAX 一样大。
## 许可证
除非文件中另有特别说明，Mbed TLS 文件是在双 [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) 或 [GPL-2.0-or-later](https://spdx.org/licenses/GPL-2.0-or-later.html) 许可证下提供的。有关这些许可证的全文，请参阅 [LICENSE](LICENSE) 文件，有关更多信息，请参阅 [贡献指南中的“许可证和版权”部分](CONTRIBUTING.md#License-and-Copyright)。
## 贡献
我们衷心接受来自社区的错误报告和。有关如何执行此操作的详细信息，请参阅 [贡献指南](CONTRIBUTING.md)。
## 联系方式
* 要报告 Mbed TLS 中的安全漏洞，请发送电子邮件至 。更多信息，请参见 [`SECURITY.md`](SECURITY.md)。
* 要报告 Mbed TLS 中的错误或请求功能，请 [在 GitHub 上提交 issue](https://github.com/Mbed-TLS/mbedtls/issues/new/choose)。
* 有关 Mbed TLS 的讨论和支持的其他渠道，请参见 [`SUPPORT.md`](SUPPORT.md)。
标签：Arm Mbed, Bash脚本, CMake, DTLS, LangChain, Mbed TLS, PSA Crypto, SSL, TLS库, X.509, 传输层安全, 加密协议, 安全通信, 客户端加密, 客户端加密, 密码学, 嵌入式系统, 开源库, 手动系统调用, 搜索引擎爬虫, 物联网安全, 网络安全, 证书管理, 轻量级, 逆向工具, 隐私保护