mbedtls

这是一个MbedTLS的惯用Rust包装器，允许您仅使用安全代码使用MbedTLS，同时能够使用像错误处理和闭包这样的优秀Rust特性。

此外，基于MbedTLS对嵌入式使用的关注，此包可以在无标准环境中使用。

构建

此包依赖于mbedtls-sys-auto包，以下为构建细节。

特性

这是mbedtls可用的Cargo特性的列表。粗体的特性是默认启用的。

• 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的支持
• no_std_deps 在无标准环境中，您必须启用此特性。它启用了无标准环境所需的可选依赖项。如果启用了std特性，则忽略此特性。
• padlock 启用对VIA padlock的支持
• pkcs12 启用使用yasna解析PKCS12文件的代码
• pkcs12_rc2 启用使用RC2包解密RC2加密的PKCS12文件
• rdrand 启用RDRAND随机数生成器。在SGX上，此特性自动启用。
• std 如果未启用此特性，则此包是一个无标准包。（需要一个分配器）将提供必要的C函数，以便MbedTLS在没有libc的情况下工作。（必须）
• time 启用mbedtls-sys中的时间支持
• zlib 启用mbedtls-sys中的zlib支持

鼓励添加新特性的PRs。

mbedtls-sys-auto

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

要使用这个crate，您需要安装clang和cmake，以下为详细说明。

配置和链接MbedTLS

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

mbedtls-sys crate包含MbedTLS源代码，MbedTLS的版本将与crate的major.minor版本相同。您可以使用环境变量RUST_MBEDTLS_SYS_SOURCE指定自己的源树路径，而不是使用提供的源代码。不建议使用基于crate中提供的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函数签名的函数mbedtls_aesni_has_support和mbedtls_padlock_has_support。在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为无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()。
• time 启用时间支持。在cfg(unix)平台上，此功能使用libc。在其他平台上，您需要提供自己的实现：mbedtls_platform_gmtime_r(const long long*, struct tm*)和mbedtls_time(long long*)。
• trusted_cert_callback 启用受信任证书回调支持。
• zlib 启用zlib支持。

有关功能到config.h定义的完整映射，请参阅mbedtls-sys/build/config.rs。鼓励提交添加新功能的PR。

MbedTLS版本更新

有关更新到新MbedTLS源代码发布版本的说明，请参阅mbedtls-sys/。

1. 删除vendor/目录，并用发行版的tarball内容替换。
2. 从上一个版本中挑选任何本地更改。
3. 使用build/headers.rs中的命令生成头文件列表，并相应地更新该文件。
4. 检查build/config.rs与vendor/include/mbedtls/config.h。
5. 更新Cargo.toml中的版本号。

mbedtls-selftest

这个Rust包旨在将需要导出Rust函数并定义C函数供C mbedtls使用的自测代码分离出来。通过分离这些代码，可以在单个包中使用不同版本的Rust mbedtls包，从而有助于解决链接名称冲突错误。

注意：虽然可以在单个包中使用多个版本的Rust mbedtls包，但由于它们作为本地库构建，因此只能使用一个mbedtls-selftest和一个mbedtls-sys-auto包。

贡献

我们感谢社区提供的错误报告和贡献。通过参与这个社区，您同意遵守行为准则。所有贡献都在开发者证书来源（DCO）的范围内。

开发者证书来源 1.1

通过向此项目做出贡献，我证明

(a) 贡献是全部或部分由我创建的，我有权根据文件中指示的开源许可证提交它；或者

(b) 贡献基于以前的工作，据我所知，这些工作受适当的开源许可证保护，并且我有权根据该许可证提交这些工作，无论是全部还是部分由我创建的，都可以根据同一开源许可证（除非我被允许使用不同的许可证）进行修改，如文件中所示；或者

(c) 贡献是由其他人直接提供给我的，该人已证明（a）、（b）或（c），并且我没有对其进行修改。

(d) 我理解并同意，该项目和贡献是公开的，并且贡献的记录（包括我提交的所有个人信息，包括我的签名）将无限期地保留，并且可以与此项目或相关的开源许可证一致地进行分发。

许可证

本项目主要根据Apache许可证版本2.0和GNU通用公共许可证版本2进行分发，有关详细信息，请参阅LICENSE-APACHE和LICENSE-GPL。

关于许可证的说明

MbedTLS采用Apache-2.0 / GPL-2.0+双重许可，mbedtls和mbedtls-sys-auto包也是如此。然而，源代码以两个不同的单许可证tarball进行分发。mbedtls和mbedtls-sys-auto包的作者不保证两个版本的MbedTLS代码完全相同。此存储库包括Apache-2.0版本。由于Apache-2.0与GPL-3.0+兼容，这可能不会对希望在GPL-3.0+许可证的项目中使用mbedtls-sys的人造成问题，但如果您想在GPL-2.0许可证的项目中使用它，您可能需要在构建时手动指定GPL-2.0源代码。