# mbedtls

**Repository Path**: embed-systems/mbedtls

## Basic Information

- **Project Name**: mbedtls
- **Description**: 一个开源的、可移植的、易于使用的、可读的和灵活的TLS库，以及PSA加密API的参考实现。发布的节奏不同，通常在3 - 6个月之间发布。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: development
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-07-08
- **Last Updated**: 2025-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Mbed TLS自述文件
===============

Mbed TLS是一个C库, 它实现了加密原语、X.509证书操作以及SSL/TLS和DTLS协议。
它的代码占用空间小，适合嵌入式系统。

Mbed TLS包括[PSA加密API](#psa-cryptography-api)的参考实现。
这目前是一个预览评估的目的.

配置
---

在大多数系统上，Mbed TLS应该是开箱即用的。在完整文档化的配置文件
`include/mbedtls/mbedtls_config.h`中提供了一些特定于平台的选项，这也是可以选择特性的地方。
该文件可以手动编辑，也可以使用Python3脚本`scripts/config.py`以更程序化的方式编辑(使用
`——help`获取使用说明)。

当使用Make和CMake构建系统(见下文)时，可以使用传统的环境变量，如`CC`和`CFLAGS`来设置编译器选项。

我们在`configs/`目录中提供了一些针对特定用例的非标准配置。你可以在`configs/README.txt`中
了解更多。

文档
---

主要的Mbed TLS文档可通过[ReadTheDocs](https://mbed-tls.readthedocs.io/)获得。

PSA加密API的文档可以在[GitHub](https://arm-software.github.io/psa-api/crypto/)上找到。

根据你的编译时配置，生成HTML格式的库文档的本地副本：

1. 确认已安装[oxygen](http://www.doxygen.nl/)。
2. 执行`make apidoc`命令。
3. 浏览`apidoc/index.html`或`apidoc/modules.html`。

有关其他文档来源，请参见[SUPPORT](SUPPORT.md)文档。

编译
---

目前在Mbed TLS版本中使用了三种活跃的构建系统：

- GNU Make
- CMake
- Microsoft Visual Studio

用于开发的主要构建系统是CMake和GNU Make。这些系统总是完整的和最新的。
其他版本应该反映CMake和Make构建系统中存在的所有更改，尽管功能可能不会自动移植到那里。

Make和CMake构建系统创建了三个库：libmbedcrypto、libmbedx509和libmbedtls。
注意，libmbedtls依赖于libmbedx509和libmbedcrypto，而libmbedx509依赖于libmbedcrypto。
因此，一些链接器将期望标志以特定的顺序排列，例如GNU链接器希望
`-lmbedtls -lmbedx509 -lmbedcrypto`。

### 工具版本

你需要以下工具来使用提供的makefiles构建库：

* GNU Make 3.82或CMake支持的构建工具。
* 一个C99工具链(编译器、链接器、归档器)。我们积极测试GCC 5.4, Clang 3.8, Arm Compiler 6,
IAR 8和Visual Studio 2017。最新的版本应该可以使用。稍微旧一点的版本也可以。
* Python 3.8生成测试代码。还需要Python来集成PSA驱动程序和构建开发分支(请参阅下一节)。
* 来运行测试，并在开发分支中生成一些源文件。
* CMake 3.10.2或更高版本(如果使用CMake)。
* Microsoft Visual Studio 2017或更高版本(如果使用Visual Studio)。
* Doxygen 1.8.11或更高版本(如果构建文档；稍微旧一点的版本应该可以使用)。

### Git使用

Mbed TLS的`开发`分支和`mbedtls-3.6`长期支持分支使用
[Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules)
([framework](https://github.com/Mbed-TLS/mbedtls-framework))。
仅仅在发布标记处编译库并不需要这样做。这并不需要使用发布归档文件(zip或tar)。

### 在开发分支中生成源文件

Mbed TLS的源代码包括一些由脚本自动生成的文件，这些文件的内容仅依赖于Mbed TLS源代码，而不依赖
于平台或库配置。这些文件不包含在Mbed TLS的开发分支中，但生成的文件包含在正式版本中。本节解释如
何在开发分支中生成缺失的文件。

需要准备的工具如下：

* Perl，用于一些库源文件和Visual Studio构建文件。
* Python 3.8和一些Python包，用于一些库源文件，示例程序和测试数据。要安装必要的软件包，请运行：

```shell
$ python3 -m pip install --user -r scripts/basic.requirements.txt
```

根据您的Python安装，您可能需要调用`python`而不是`python3`。要在系统范围内安装软件包，请省略`——user`选项。

* 一个针对主机平台的C编译器，用于一些测试数据。

如果是交叉编译，在生成与配置无关的文件时，必须将`CC`环境变量设置为主机平台的C编译器。

生成与配置无关的文件有以下两种方法：

* 如果没有交叉编译，对任何目标运行`make`，或者只运行`make`，将自动生成所需的文件。
* 在非Windows系统上，当不进行交叉编译时，CMake将自动生成所需的文件。
* 执行`make generated_files`命令生成所有与配置无关的文件。
* 在Unix/POSIX系统上，运行`tests/scripts/check-generated-files.sh -u`生成所有与配置
无关的文件。
* 在Windows上，运行 `scripts\make_generated_files.bat`生成所有与配置无关的文件。

### Make

我们需要GNU Make。要构建库和示例程序，GNU Make和C编译器就足够了。一些更高级的构建目标需要一些Unix/Linux工具。

我们有意在makefile中只使用最少的功能，以保持它们尽可能简单和独立于不同的工具链，允许用户更容易地在不同的平台之间移动。建议需要更多功能的用户使用CMake。

为了使用GNU Make从源代码构建，只需在命令行输入：

```shell
$ make
```

要运行测试，请输入：

```shell
$ make check
```

测试需要构建Python并运行Perl。如果您没有安装其中一个，您可以使用以下命令跳过构建测试：

```shell
$ make no_test
```

您仍然可以通过以下方式运行小得多的测试集：

```shell
$ programs/test/selftest
```

为了构建Windows平台，如果目标是Windows，但构建环境是类unix的(例如交叉编译或从MSYS shell编译时)，则应该使用`WINDOWS_BUILD=1`，如果构建环境是Windows shell(例如使用mingw32-make)(在这种情况下，某些目标将不可用)。

在环境中设置变量`SHARED`将构建除静态库之外的共享库。设置`DEBUG`会给你一个调试版本。您可以通过在您的环境或make命令行中设置`CFLAGS`和`LDFLAGS`来覆盖它们；编译器警告选项可以使用`WARNING_CFLAGS`单独覆盖。一些特定于目录的选项(例如，`-I`指令)仍然被保留。

请注意，设置`CFLAGS`会覆盖它的默认值`-O2`，设置`WARNING_CFLAGS`会覆盖它的默认值(以`-Wall -Wextra`开头)，所以如果你只是想在默认选项中添加一些警告选项，你可以通过设置`CFLAGS=-O2 -Werror`来实现。设置`WARNING_CFLAGS`是有用的，当你想摆脱其默认内容(例如，因为你的编译器不接受`-Wall`作为一个选项)。不能从命令行重写特定于目录的选项。

根据您的平台，您可能会遇到一些问题。请检查`library/`、`programs/`和`tests/`中的makefile，以获取手动添加或删除特定平台的选项。您也可以查看[Mbed TLS知识库](https://mbed-tls.readthedocs.io/en/latest/kb/)，查看您的平台或问题上的文章。

如果您发现您还需要做其他事情，请告诉我们，以便我们将其添加到[Mbed TLS知识库](https://mbed-tls.readthedocs.io/en/latest/kb/)。

### CMake

为了使用CMake在一个单独的目录(推荐)中构建源代码，只需在命令行中输入：

```shell
$ mkdir /path/to/build_dir && cd /path/to/build_dir
$ cmake /path/to/mbedtls_source
$ cmake --build .
```

要运行测试，请输入：

```shell
$ ctest
```

测试套件需要构建Python并执行Perl。如果你没有安装其中一个，你会想要禁用测试套件：

```shell
$ cmake -DENABLE_TESTING=Off /path/to/mbedtls_source
```

如果禁用了测试套件，但保持程序启用，则仍然可以使用以下方法运行小得多的测试集：

```shell
$ programs/test/selftest
```

要配置CMake来构建共享库，使用：

```shell
$ 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工具来检查未初始化的内存读取。实验性的，需要Linux/x86\_64上的最新clang。
- `MemSanDbg` 与MemSan相同，但速度较慢，具有调试信息，更好的堆栈跟踪和原点跟踪。
- `Check` 这将激活依赖于优化的编译器警告，并将所有警告视为错误。

在CMake中切换构建模式很简单。对于调试模式，在命令行输入：

```shell
$ cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source
```

要列出其他可用的CMake选项，使用：

```shell
$ cmake -LH
```

注意，使用CMake，你不能在初始调用CMake后调整编译器或其标志。这意味着`CC=your_cc make`和`make CC=your_cc`将不起作用(类似于`CFLAGS`和其他变量)。这些变量需要在第一次调用cmake时进行调整，例如：

```shell
$ CC=your_cc cmake /path/to/mbedtls_source
```

如果您已经调用了cmake并希望更改这些设置，则需要删除构建目录并重新创建它。

请注意，可以就地构建；然而，这将覆盖提供的makeffiles(如果你想防止`git status`显示它们被修改，请参阅`scripts/tmp_ignore_makeffiles.sh`)。为此，在Mbed TLS源目录中使用：

```shell
$ cmake .
$ make
```

如果你想改变`CC`或`CFLAGS`之后，你将需要删除CMake缓存。这可以用下面的使用GNU命令find来完成：

```shell
$ find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
```

现在，您可以进行所需的更改：

```shell
$ CC=your_cc cmake .
$ make
```

关于变量，还要注意，如果您在调用cmake时设置CFLAGS，则CFLAGS的值不会覆盖cmake提供的内容(取决于上面看到的构建模式)，它只是添加到cmake中。

#### 使用Mbed TLS

Mbed TLS提供了一个包配置文件，作为其他CMake项目的依赖项使用。你可以自己包含Mbed TLS的CMake目标：

```shell
find_package(MbedTLS)
```

如果出现提示，将`MbedTLS_DIR`设置为`${YOUR_MBEDTLS_INSTALL_DIR}/cmake`。这会创建以下目标：

- `MbedTLS::mbedcrypto` (Crypto library)
- `MbedTLS::mbedtls` (TLS library)
- `MbedTLS::mbedx509` (X509 library)

然后你可以通过`target_link_libraries()`直接使用它们：

```shell
add_executable(xyz)

target_link_libraries(xyz
    PUBLIC MbedTLS::mbedtls
           MbedTLS::mbedcrypto
           MbedTLS::mbedx509)
```

这将把Mbed TLS库链接到您的库或应用程序，并将其包含目录添加到您的目标(传递地，在`PUBLIC`或`INTERFACE`链接库的情况下)。

#### Mbed TLS作为子项目

Mbed TLS支持作为CMake子项目构建。可以从父CMake项目中使用`add_subdirectory()`来包含Mbed TLS作为子项目。

### Microsoft Visual Studio

Microsoft Visual Studio的构建文件是为Visual Studio 2017生成的。

解决方案文件`mbedTLS.sln`包含构建库和所有程序所需的所有基本项目。测试中的文件不会生成和编译，因为它们也需要Python和Perl环境。但是，“programs/test/”中的自测程序仍然可用。

在Mbed TLS的开发分支中，需要首先按照[“在开发分支中生成源文件”](#generated-source-files-in-the-development-branch)中的描述生成Visual Studio解决方案文件。

示例程序
------

我们在[`programs/`](programs/README.md)中包含了许多不同功能和用途的示例程序。
请注意，这些示例程序的目的是演示库的特定功能，代码可能需要进行调整以构建真实的应用程序。

测试
---

Mbed TLS在`tests/`中包含一个复杂的测试套件，最初需要Python生成测试文件(例如：
`test\_suite\_mpi.c`)。这些文件是从“函数文件”(例如：·suites/test\_suite\_mpi.function`)
和“数据文件”(例如：`suites/test\_suite\_mpi.data`)。“函数文件”包含测试函数。“数据文件”包含测试用例，指定为将传递给测试功能的参数。

对于安装了Unix shell和OpenSSL(以及可选的GnuTLS)的机器，可以使用额外的测试脚本：

- `tests/ssl-opt.sh` 为各种TLS选项(重新协商、恢复等)运行集成测试，并测试这些选项与其他实现的互操作性。
- `tests/compat.sh` 测试每个密码套件与其他实现的互操作性。
- `tests/scripts/test-ref-configs.pl` 在各种简化配置中测试构建。
- `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一样大。

PSA密码学API
-----------

### PSA API

ARM的[平台安全架构(PSA)](https://developer.arm.com/architectures/security-architectures/platform-security-architecture)是一套完整的威胁模型、安全分析、硬件和固件架构规范以及开源固件参考实现。PSA提供了一种基于行业最佳实践的方法，允许在硬件和固件级别上一致地设计安全性。

[PSA加密API](https://arm-software.github.io/psa-api/crypto/)提供了对一组加密原语的访问。它有双重目的。首先，它可以在符合PSA的平台中用于构建服务，例如安全引导、安全存储和安全通信。其次，它还可以独立于任何平台上的其他PSA组件使用。

PSA加密API的设计目标包括：

* API将调用者内存与内部内存区分开来，从而允许在隔离的空间中实现库，以获得额外的安全性。如果不需要隔离，库调用可以实现为直接函数调用，如果需要隔离，则可以实现为远程过程调用。
* 内部数据的结构对应用程序是隐藏的，这允许在构建时或运行时替换其他实现，例如，为了利用硬件加速器。
* 所有对密钥的访问都是通过密钥标识符进行的，这允许支持对应用程序透明的外部加密处理器。
* 算法的接口是通用的，有利于算法的敏捷性。
* 该接口被设计为易于使用和防止意外误用。

ARM欢迎对API设计的反馈。如果你认为有什么可以改进的，请在我们的Github存储库上打开一个问题。或者，如果您愿意私下提供您的反馈，请发送电子邮件至[`mbed-crypto@arm.com`](mailto:mbed-crypto@arm.com)。所有通过电子邮件收到的反馈都将被保密。

### Mbed TLS中的PSA实现

Mbed TLS包括PSA加密API的参考实现。然而，它的目标不是实现整个规范；特别是它没有实现所有的算法。

X.509和TLS代码可以对大多数操作使用PSA加密。要启用此支持，请激活`mbedtls_config.h`中的编译选项`MBEDTLS_USE_PSA_CRYPTO`。请注意，TLS 1.3对大多数操作使用PSA加密，而不考虑此选项。见`docs/use-psa-crypto.md`了解详情。

### PSA驱动

Mbed TLS支持加密加速器、安全元素和随机生成器的驱动程序。这项工作还在进行中。请注意，驱动程序接口尚未完全稳定，可能会在不通知的情况下更改。我们打算保持应用程序代码的向后兼容性(使用PSA Crypto API)，但是在未来的Mbed TLS小版本中，驱动程序的代码可能必须更改。

有关编写驱动程序的信息，请参阅[PSA驱动程序示例和指南](docs/psa-driver-example-and-guide.md)。

在使用驱动程序时，通常需要启用两个编译选项(请参阅参考手册以获取更多信息)：

* `MBEDTLS_USE_PSA_CRYPTO`是必需的，以便X.509和TLS代码调用PSA驱动程序而不是内置的软件实现。
* `MBEDTLS_PSA_CRYPTO_CONFIG`允许您启用PSA加密机制，而不包括相应软件实现的代码。这还不是所有机制都支持的。

许可证
-----

除非文件中另有明确说明，否则Mbed TLS文件是在双重[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)或[GPL-2.0或更高版本](https://spdx.org/licenses/GPL-2.0-or-later.html)许可下提供的。请参阅[许可证](LICENSE)文件以获取这些许可证的全文，并参阅[贡献指南中的'许可证和版权'部分](CONTRIBUTING.md#许可证和版权)以获取更多信息。

### 包含在Mbed TLS中的第三方代码

此项目包含来自其他项目的代码。该代码位于`3rdparty/`目录中。原始许可证文本包含在项目子目录中，它与普通的Mbed TLS许可证不同，并且/或包含在源文件中。项目列表如下：

* `3rdparty/everest/`：文件源于[Project everest](https://project-everest.github.io/)，并在Apache 2.0许可下分发。
* `3rdparty/p256-m/p256-m/`: 文件是从[p256-m](https://github.com/mpg/p256-m)存储库中获取的。原始存储库中的代码在Apache 2.0许可下发布。它在经过作者许可的情况下，在Apache-2.0或GPL-2.0或更高版本的双重许可下以Mbed TLS分发。

贡献
---

我们感激地接受来自社区的bug报告和贡献。请参阅[贡献指南](CONTRIBUTING.md)了解如何做到这一点的详细信息。

联系
---

* 要报告Mbed TLS中的安全漏洞，请发送电子邮件<mbed-tls-security@lists.trustedfirmware.org>。有关更多信息，请参阅[`SECURITY.md`](SECURITY.md)。
* 要报告Mbed TLS中的错误或请求功能，请[在GitHub上提交问题](https://github.com/Mbed-TLS/mbedtls/issues/new/choose)。
* 有关Mbed TLS的讨论和支持，请参阅[`SUPPORT.md`](SUPPORT.md)。