[!WARNING] 此存储库的状态已更改为维护状态。我们不会接受任何更多功能请求。请检查 状态变更 以获取详细信息

mbedtls

这是一个 MbedTLS 的惯用 Rust 包装器，允许您使用仅包含安全代码的 MbedTLS，同时能够使用 Rust 的错误处理和闭包等出色功能。

此外，鉴于 MbedTLS 专注于嵌入式使用，此软件包也可以用于无 std 环境。

状态变更

我们发现 mbedtls 3.4.X 不是线程安全的，并且无法与多个线程正确工作。这个问题在短时间内不会得到解决。并且新的 PSA 方法不符合我们的需求。

因此，我们现在决定继续使用 mbedtls 2.28.X；此存储库的状态已更改为维护。我们不会接受任何更多功能请求。

mbedtls 3.X 的旧代码已从 master 分支移动到分支 mbedtls-3。

相关问题： #320

参考链接

• 设计变更
  • https://lists.trustedfirmware.org/archives/list/[email protected]/message/RJ7YPNBNWUNW2ICQJ72H2JMKPDKGQOLT/
• 错误
  • https://github.com/fortanix/rust-mbedtls/issues/301
  • https://github.com/fortanix/rust-mbedtls/issues/293
  • https://github.com/Mbed-TLS/mbedtls/issues/3263

构建

此软件包依赖于 mbedtls-sys-auto 软件包，有关构建详细信息，请参阅以下内容。

功能

这是 mbedtls 可用的 Cargo 功能列表。功能在

• x509 启用 PKI 功能。由该功能启用的主要代码位于 x509 模块中。

• ssl 启用 ssl/tls 功能。由该功能启用的主要代码位于 ssl 模块中。

注意：上述功能被引入，以便该包可以作为仅用于加密（或 PKI）的库使用。

粗体 默认启用。

• aesni 启用对 AES-NI 指令的支持。在 SGX 上，此功能自动启用。
• debug 启用将调试打印到 stdout。您需要在运行时配置调试阈值。
• dsa 启用对 DSA 签名的支持
• force_aesni_support MbedTLS 通常使用运行时检测 AES-NI 支持。具有此功能时，始终使用 AES-NI。这可能导致在不支持的处理器上出现未定义指令异常。在 SGX 上，此功能自动启用。
• mpi_force_c_code 在 mbedtls-sys 中启用 mpi_force_c_code 功能
• legacy_protocols 启用对 SSLv3、TLSv1.0 和 TLSv1.1 的支持。这意味着 ssl。
• no_std_deps 在 no_std 上，您必须启用此功能。它启用了在 no_std 上需要的可选依赖项。如果启用了 std 功能，则忽略此功能。
• padlock 启用对 VIA padlock 的支持。
• pkcs12 启用使用 yasna 解析 PKCS12 文件的代码。这意味着 x509。
• pkcs12_rc2 启用使用 RC2 crate 解密 RC2 加密的 PKCS12 文件。
• rdrand 启用 RDRAND 随机数生成器。在 SGX 上，此功能自动启用。
• std 如果未启用此功能，则此包是一个 no_std 包。（需要一个分配器）将提供必要的 C 函数，以便 MbedTLS 可以在没有 libc 的情况下工作。
• time 在 mbedtls-sys 中启用时间支持。
• zlib 在 mbedtls-sys 中启用 zlib 支持。
• async-rt 启用 SSL 的异步支持。
• chrono 启用 chrono 支持（例如，在 x509::Time 和 chrono 类型之间实现转换特性）

mbedtls-sys-auto

不幸的是，crates.io 上的 mbedtls-sys 包已被另一个显然不活跃的项目声称。

要使用此包，您需要安装 clang 和 cmake，下面将详细介绍。

配置和链接 MbedTLS

MbedTLS 有许多编译时配置选项，这些选项会显著影响可用的功能。为了确保 Rust 的 MbedTLS 视图与 C 中构建的内容相匹配，必须使用 Cargo 功能（见下一节）配置 MbedTLS 并使用 mbedtls-sys 的构建脚本来构建。

mbedtls-sys 包包含 MbedTLS 源代码，MbedTLS 版本将与包的 major.minor 版本相同。您可以使用提供的源代码，也可以使用 RUST_MBEDTLS_SYS_SOURCE 环境变量指定您自己的源代码树。不建议使用与包中提供的 MbedTLS 版本不同的 MbedTLS 版本的自定义源代码。

构建脚本将执行以下步骤

1. 生成适当的 config.h（忽略任何现有 config.h），
2. 编译一个静态链接的 MbedTLS，这需要安装 cmake，
3. 根据配置生成 Rust 绑定，这需要安装 clang。

功能

这是 mbedtls-sys 可用的 Cargo 功能列表。粗体功能默认启用。

• aesni 启用对 AES-NI 指令的支持。在 SGX 上，此功能自动启用。
• aes_alt 允许 AES 的替代实现，替换 T-tables 代码。
• custom_has_support 覆盖运行时功能检测。在依赖项包中，您必须定义函数 mbedtls_aesni_has_support 和 mbedtls_padlock_has_support，这些函数的签名与 MbedTLS 函数签名相同。在 SGX 上，此功能自动启用。
• custom_printf 提供自定义的 printf 实现。printf 仅用于自测试。在依赖的 crate 中，必须定义具有标准 printf 签名的 mbedtls_printf 函数。
• debug 启用调试回调。
• havege 启用硬件挥发熵收集和扩展（HAVEGE）算法。
• legacy_protocols 启用对 SSLv3、TLSv1.0 和 TLSv1.1 的支持。
• mpi_force_c_code 当可用时，MbedTLS 使用汇编代码进行 MPI 函数，在某些情况下，我们可能更愿意使用 C 代码。在 x86 平台上尤其如此，因为需要编译时缓解推测执行（例如，LVI）。让编译器在 C 代码编译期间插入所需的 lfences 可能会产生比让编译器在汇编代码上应用缓解更快的代码。
• padlock 启用对 VIA padlock 的支持。
• pkcs11 启用 PKCS#11 支持。这需要安装 pkcs11-helper。
• std 如果此功能未启用，则此 crate 为 no_std crate。在无 libc 的 no_std 配置中，您需要提供以下标准 C 函数的版本：calloc()/free()，以及 strstr()/strlen()/strncpy()/strncmp()/strcmp()/ snprintf() 和 memmove()/memcpy()/memcmp()/memset()，以及 rand()/printf()。对于 printf()，您可以选择使用 custom_printf 功能。rand() 仅在自测试中需要。在 UNIX 平台上，这还启用了网络、文件系统和 OS 熵。
• threading 启用线程支持。在 cfg(unix) 平台上，此功能使用 pthreads。在其他平台上，您需要提供一个自定义的线程实现。在依赖的 crate 中，必须根据 MbedTLS 函数签名定义以下函数：mbedtls_mutex_init()、mbedtls_mutex_free()、mbedtls_mutex_lock() 和 mbedtls_mutex_unlock()。
• 时间 启用时间支持。在 cfg(unix) 平台上，这使用 libc。在其他平台上，您需要提供自己的 mbedtls_platform_gmtime_r(const long long*, struct tm*) 和 mbedtls_time(long long*) 的实现。
• trusted_cert_callback 启用受信任证书回调支持。
• zlib 启用 zlib 支持。