Mbed-TLS/TF-PSA-Crypto
GitHub: Mbed-TLS/TF-PSA-Crypto
提供符合 PSA 密码学 API 1.2 的参考实现，解决跨平台安全密码原语访问与硬件加速集成问题。
Stars: 45 | Forks: 92
# TF-PSA-Crypto 的 README
TF-PSA-Crypto 仓库提供了
[PSA 密码学 API 版本 1.2](https://arm-software.github.io/psa-api/crypto/1.2/)
的实现，限制在于
[PAKE 扩展](https://arm-software.github.io/psa-api/crypto/1.2/ext-pake/)
的实现仍存在一些不合规情况，例如返回的错误码。
PSA 密码学 API 的实现围绕
[PSA 密码学驱动接口](docs/proposed/psa-driver-interface.md)
构建，旨在简化对密码加速器与处理器的支持。
## PSA 密码学 API
[PSA 密码学 API](https://arm-software.github.io/psa-api/crypto/)
提供对一组密码原语（primitive）的访问。它具有双重用途。
首先，它可在 PSA 兼容平台上用于构建服务，例如
安全启动、安全存储和安全通信。其次，它也可以独立于其他 PSA 组件在任何平台上使用。
PSA 密码学 API 的设计目标包括：
* API 将调用方内存与内部内存分离，这允许库在隔离空间中实现以提升安全性。
如果不需要隔离，库调用可以实现为直接函数调用；如果需要隔离，则可以实现为远程过程调用。
* 内部数据的结构对应用程序隐藏，这允许在构建时或运行时替换替代实现，
例如为了利用硬件加速器。
* 所有密钥访问都通过密钥标识符进行，这允许对应用程序透明地支持外部密码处理器。
* 算法接口是通用的，倾向于算法灵活性。
* 接口设计得易于使用且难以意外误用。
我们欢迎对 API 设计提出反馈。如果您认为可以改进，请在我们的 GitHub 仓库上
[提交问题](https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/new/choose)。或者，如果您更愿意私下提供反馈，请通过电子邮件联系
[`mbed-crypto@arm.com`](mailto:mbed-crypto@arm.com)。所有通过电子邮件收到的反馈都会保密处理。
### TF-PSA-Crypto 中的 PSA 密码学 API 实现
TF-PSA-Crypto 包含一个 PSA 密码学 API 的实现。它覆盖了
大部分，但并非全部算法。
### PSA 密码学驱动接口
TF-PSA-Crypto 支持用于密码加速器、安全元件和随机数生成器的驱动。
这是一项正在进行中的工作。请注意，驱动接口尚未完全稳定，可能会在未通知的情况下变更。
我们打算保持对应用程序代码（使用 PSA 密码学 API）的向后兼容性，
但驱动代码可能需要在 TF-PSA-Crypto 的小版本发布中变更。
有关编写驱动的详细信息，请参阅
[PSA 驱动示例与指南](docs/psa-driver-example-and-guide.md)。
## 配置
TF-PSA-Crypto 仓库应该可以在大多数系统上开箱即用构建。
其配置基于在
`include/psa/crypto_config.h`
中定义 C 预处理器宏。
这些配置选项分为七个组：
1. 密码机制选择（PSA API）：PSA_WANT_xxx 宏用于指定用户希望启用的 PSA 密码学 API 部分，
例如加密算法、密钥类型、椭圆曲线。
2. 平台抽象层：用于适配库到不同平台的选项。
3. 常规和测试配置选项：与测试相关或不与库特定部分相关的选项。
4. 密码机制选择（扩展 API）：用于启用超出当前 PSA 密码学 API 的密码机制，
例如 LMS 或密钥封装。
5. 数据格式支持：用于启用对各种数据格式的支持，
例如 ASN.1 或 PEM。
6. PSA 核心：用于配置密钥管理、随机数生成等非密码机制的组件。
7. 内置驱动：用于配置内置密码机制的非功能性方面，例如性能/体积权衡。
文件 `include/psa/crypto_config.h` 可以手动编辑，
或者以编程方式使用 Python 脚本 `scripts/config.py` 编辑（使用 `--help` 获取用法说明）。
我们提供了一些专注于特定使用场景的非标准配置，位于
`configs/` 目录中。更多细节请参见 `configs/README.txt`。
## 文档
PSA 密码学 API 的文档可在
[GitHub](https://arm-software.github.io/psa-api/crypto/)
上获取。
要生成本地 HTML 格式的库文档：
1. 确保已安装 [Doxygen](http://www.doxygen.nl/)。
2. 运行 `cmake -B /path/to/build_dir /path/to/TF-PSA-Crypto/source`
3. 运行 `cmake --build /path/to/build_dir --target tfpsacrypto-apidoc`
4. 打开生成的 HTML 文件之一：
* `apidoc/index.html`
* `apidoc/modules.html` 或 `apidoc/topics.html`
## 编译
构建系统使用 CMake。
CMake 构建系统会创建一个库：libtfpsacrypto。
### 工具版本
需要以下工具来从主分支构建库（使用提供的 CMake 文件）。
TF-PSA-Crypto 对工具的最小版本要求基于主要 Linux 发行版最新或倒数第二个
长期支持（LTS）版本发布时使用的版本，
即撰写时为：Ubuntu 22.04、RHEL 9 和 SLES 15 SP4。
* 一个 C99 工具链（编译器、链接器、归档器）。我们积极测试 GCC 5.4、
Clang 3.8 和 Arm Compiler 6.21。更新版本应可工作。稍旧版本也可能可用。
* Python 3.8 或更高版本，用于生成部分源文件（见下文）、测试代码和示例程序。
* CMake 3.20.2 或更高版本。
* 用于生成构建文件的构建系统，如 Make 或 Ninja。
* Microsoft Visual Studio 2019 或更高版本（若使用 Visual Studio）。
* Doxygen 1.8.14 或更高版本。
### Git 使用
受支持的（参见 [`BRANCHES.md`](BRANCHES.md)）分支使用 [Git 子模块](https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules)
[framework](https://github.com/TF-PSA-Crypto/mbedtls-framework)。
发布标签也使用 Git 子模块。
克隆仓库或检出分支/标签后，请运行：
```
git submodule update --init
```
以初始化并更新子模块后再进行构建。
不过，官方源码发布包（例如 [tf-psa-crypto-1.0.0.tar.bz2](https://github.com/Mbed-TLS/TF-PSA-Crypto/releases/download/tf-psa-crypto-1.0.0/tf-psa-crypto-1.0.0.tar.bz2)）
已包含子模块内容。
### 开发分支中的生成源文件
开发分支中的源代码包含一些由脚本自动生成的文件，
其内容仅依赖于 TF-PSA-Crypto 源码，而不依赖平台或库配置。
这些文件未包含在开发分支中，但会包含在官方发布版本中。
本节说明了如何在开发分支中生成缺失的文件。
需要以下工具：
* 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/tf/psa/crypto/source
cmake --build .
```
运行测试时，请执行：
```
ctest
```
测试套件需要 Python 构建。如果未安装 Python，
请通过以下选项禁用测试套件：
```
cmake -DENABLE_TESTING=Off /path/to/tf/psa/crypto/source
```
要配置以构建共享库，请使用：
```
cmake -DUSE_SHARED_TF_PSA_CRYPTO_LIBRARY=On /path/to/tf/psa/crypto/source
```
在 CMake 构建系统中有多种构建模式可用。
其中大多数适用于 gcc 和 clang，部分为编译器专用：
- `Release`：生成默认代码，不包含二进制文件中的额外信息。
- `Debug`：生成调试信息并关闭代码优化。
- `ASan`：使用 AddressSanitizer 检测内存错误（包含 LeakSanitizer）。
- `ASanDbg`：同 ASan 但更慢，包含调试信息和更优堆栈回溯。
- `MemSan`：使用 MemorySanitizer 检测未初始化内存读取（实验性）。
- `MemSanDbg`：同 MemSan 但更慢，包含调试信息和更优堆栈回溯。
- `Check`：启用依赖优化的编译器警告，并将所有警告视为错误。
- `TSan`：使用 ThreadSanitizer 检测数据竞争与线程相关并发问题。
- `TSanDbg`：同 TSan 但更慢，包含调试信息和更优堆栈回溯。
切换 CMake 构建模式很简单。要进入调试模式，请在命令行中执行：
```
cmake -D CMAKE_BUILD_TYPE=Debug /path/to/tf/psa/crypto/source
```
要列出所有可用的 CMake 选项，请使用：
```
cmake -LH
```
注意：使用 CMake 时，无法在首次调用 cmake 后调整编译器或其标志。
这意味着 `CC=your_cc make` 和 `make CC=your_cc` **不会生效**（对 `CFLAGS` 及其他变量同样如此）。
这些变量必须在首次调用 cmake 时设置，例如：
```
CC=your_cc cmake /path/to/tf/psa/crypto/source
```
若已调用 cmake 并希望更改这些设置，需要再次运行配置阶段并传入新设置。
注意可以以就地方式构建，使用：
```
cmake .
cmake --build .
```
关于变量，还需注意：如果在调用 cmake 时设置了 CFLAGS，
你的 CFLAGS 值不会覆盖 CMake 提供的值（取决于上述构建模式），
而是会被前置到已有内容之前。
### 使用 TF-PSA-Crypto
TF-PSA-Crypto 为其他 CMake 项目提供 CMake 包配置文件，可作为依赖项使用。
加载其 CMake 库目标：
```
find_package(TF-PSA-Crypto)
```
你可以帮助 CMake 找到该包：
- 通过设置变量 `TF-PSA-Crypto_DIR` 为 `${YOUR_TF_PSA_CRYPTO_BUILD_DIR}/cmake`，
示例如 `programs/test/cmake_package/CMakeLists.txt`；或
- 将 TF-PSA-Crypto 的安装前缀添加到 `CMAKE_PREFIX_PATH`，
示例如 `programs/test/cmake_package_install/CMakeLists.txt`。
成功执行 `find_package(TF-PSA-Crypto)` 后，
目标 `TF-PSA-Crypto::tfpsacrypto` 即可用。
随后可直接通过 `target_link_libraries()` 使用：
```
add_executable(xyz)
target_link_libraries(xyz PUBLIC TF-PSA-Crypto::tfpsacrypto)
```
这会将 TF-PSA-Crypto 库链接到你的库或应用程序，
并将其包含目录传递给你的目标（传递性依赖，
在 `PUBLIC` 或 `INTERFACE` 链接库时生效）。
#### 作为子项目使用
TF-PSA-Crypto 仓库支持作为 CMake 子项目构建。
可通过 `add_subdirectory()` 从父 CMake 项目中包含 TF-PSA-Crypto。
### Microsoft Visual Studio
TF-PSA-Crypto 库可使用已正确安装 CMake 的 Microsoft Visual Studio Community 构建。
关于 Visual Studio 中 CMake 项目的通用文档，请参考其官方文档。
以下说明已在 Microsoft Visual Studio Community 2019
版本 16.11.26 上测试通过。TF-PSA-Crypto 库及其测试开箱即用：
* 安装 Visual Studio Community，包含默认的 “Desktop development with C++”
和 “Python development” 工作负载。
* 安装 Python 库以用于代码和测试生成，如 `basic.requirements.txt` 中定义。
有关 Visual Studio 中的 Python 环境，请参考其文档。
* 克隆 TF-PSA-Crypto 仓库时，CMakeSettings.json 会在仓库根目录创建。
在该文件中，添加
`"environments": [ {"CC" : "cl"} ]`
到配置项中。这样在构建库及其测试时，
会设置 CC 环境变量值为 “cl”。这对于生成测试用例的 Python 脚本是必需的。
CMakeSettings.json 可通过 **Project > CMake Settings for TF-PSA-Crypto > Edit JSON** 编辑。
* 如有必要（可能在更新 CMakeSettings.json 后自动完成），生成 CMake 缓存：
**Project > Generate Cache**
* 构建库：**Build > Build All**
* 可运行测试套件：**Test > Run CTests for TF-PSA-Crypto**
## 示例程序
我们已在
[`programs/`](programs/README.md)
中包含用于不同特性和用途的示例程序。
请注意，这些示例程序的目的是展示库的具体功能，
代码可能需要适配才能用于实际应用。
## 测试
TF-PSA-Crypto 仓库包含一个完善的测试套件，位于 `tests/` 目录，
最初需要 Python 来生成测试文件
（例如 `test_suite_psa_crypto.c`）。
这些文件由一个 `function file`（如 `suites/test_suite_psa_crypto.function`）
和一个 `data file`（如 `suites/test_suite_psa_crypto.data`）生成。
`function file` 包含测试函数，`data file` 包含作为参数传递给测试函数的测试用例。
## 移植 TF-PSA-Crypto
TF-PSA-Crypto 可移植到多种架构、操作系统与平台。
在开始移植之前，以下知识库文章可能有用：
- [将 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/)
TF-PSA-Crypto 主要使用可移植的 C99 编写；
但它有一些超出标准但大多数现代架构都能满足的平台要求：
- 字节必须为 8 位。
- 全零表示必须是指针的有效表示。
- 有符号整数必须使用补码表示。
- `int` 和 `size_t` 宽度至少为 32 位。
- 必须提供 `uint8_t`、`uint16_t`、`uint32_t` 及其有符号对应类型。
- 不支持混合大小端平台。
- SIZE_MAX 必须至少与 INT_MAX 和 UINT_MAX 一样大。
## 许可证
除非文件中另有明确说明，TF-PSA-Crypto 文件均采用双重许可：
[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) 文件。
### 包含的第三方代码
本项目包含来自其他项目的代码。
这些代码位于 `drivers/` 目录中。
原始许可证文本包含在项目子目录中（如果与常规 Mbed TLS 许可证不同），
或者位于源文件中。
涉及的工程包括：
* `drivers/everest/`：源自 [Project Everest](https://project-everest.github.io/)，采用 Apache 2.0 许可证。
* `drivers/p256-m/p256-m/`：代码取自 [p256-m](https://github.com/mpg/p256-m) 仓库。
原始仓库采用 Apache 2.0 许可证。
在 TF-PSA-Crypto 中采用双重许可（Apache-2.0 **或** GPL-2.0-or-later），并获得作者许可。
## 贡献
我们衷心感谢社区提交的 Bug 报告与贡献。
请参阅 [贡献指南](CONTRIBUTING.md) 获取详细信息。
## 联系
* 如需报告 TF-PSA-Crypto 的安全漏洞，请发送邮件至 。
更多信息请参见 [`SECURITY.md`](SECURITY.md)。
* 如需报告 Bug 或请求功能，请[在 GitHub 上提交问题](https://github.com/Mbed-TLS/TF-PSA-Crypto/issues/new/choose)。
* 如需其他讨论与支持，请参考 [`SUPPORT.md`](SUPPORT.md)。
标签：Bash脚本, Golang, PAKE, PSA Cryptography API, PSA驱动接口, TF-PSA-Crypto, 内存隔离, 加密API, 参考实现, 可移植加密, 安全启动, 安全存储, 安全编程, 安全通信, 客户端加密, 嵌入式安全, 操作系统检测, 硬件加速, 算法敏捷性, 远程过程调用, 逆向工具, 错误码处理, 驱动接口