[!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 模块中。

注意：上述功能是为了使此 crate 能够用作仅用于加密（或 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 如果未启用此功能，则此 crate 是 no_std crate。（需要一个分配器）将提供必要的 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 crate 被另一个显然不活跃的项目所声称。

要使用此 crate，您需要安装 clang 和 cmake，下面提供详细信息。

配置和链接 MbedTLS

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

mbedtls-sys crate 包含 MbedTLS 源代码，MbedTLS 版本将与 crate 的主要.minor 版本相同。您可以使用提供的源代码，也可以使用 RUST_MBEDTLS_SYS_SOURCE 环境变量指定您自己的源树路径。不建议使用基于与 crate 中提供的 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 覆盖运行时功能检测。在依赖项 crate 中，您必须定义 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 平台上，需要编译时缓解 speculative execution（例如，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 平台上，这也启用了网络、文件系统和操作系统熵。
• 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 支持。