mbedTLS 2.14.1

mbedTLS 2.14.1

×

由Glenn Schmidt维护。

mbedTLS 2.14.1

  • 由
  • ARM Limited

Mbed TLS的README

配置

Mbed TLS应在大多数系统上默认构建。一些特定平台选项可在完全文档化的配置文件include/mbedtls/config.h中找到，该文件也是选择特性的地方。此文件可以手动编辑，或者使用Perl脚本scripts/config.pl以更程序化的方式进行编辑（使用--help获取使用说明）。

当使用Make和CMake构建系统时，可以使用传统环境变量（如CC和CFLAGS）设置编译器选项。

编译

在Mbed TLS版本中目前有三种活跃的构建系统

  • GNU Make
  • CMake
  • Microsoft Visual Studio (Microsoft Visual Studio 2010或更高版本)

用于开发的系统主要是CMake和GNU Make。这些系统始终完整且处于最新状态。其他的应该反映CMake和Make构建系统中的所有更改，尽管可能不会自动将其移植到那里。

Make和CMake构建系统创建三个库：libmbedcrypto、libmbedx509和libmbedtls。请注意，libmbedtls依赖于libmbedx509和libmbedcrypto，libmbedx509依赖于libmbedcrypto。因此，一些链接器可能会期待在特定顺序中放置标志，例如GNU链接器想要-lmbedtls -lmbedx509 -lmbedcrypto。此外，在加载共享库时使用dlopen()后，您需要先加载libmbedcrypto，然后是libmbedx509，然后再加载libmbedtls。

Make

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

为了保持makefile尽可能简单且不依赖于不同的工具链，我们特意只使用了最基本的功能，以便用户更容易在不同平台之间移动。需要更多功能的用户建议使用CMake。

要使用GNU Make从源代码构建，只需在命令行中输入

make

要运行测试，请输入

make check

测试需要Perl来构建和运行。如果您未安装Perl，可以使用以下命令跳过构建测试

make no_test

您仍可以使用以下方式运行一组更小的测试

programs/test/selftest

要为Windows平台构建，如果目标是Windows但构建环境是类Unix环境（例如交叉编译或在MSYS shell中编译），请使用WINDOWS_BUILD=1；如果构建环境是Windows shell（例如使用mingw32-make），则使用WINDOWS=1（在这种情况下，某些目标可能不可用）。

在您的环境中设置变量SHARED将在构建静态库的同时构建共享库。设置DEBUG将为您提供调试构建。您可以通过在环境或make命令行中设置它们来覆盖CFLAGS和LDFLAGS；可以通过使用WARNING_CFLAGS单独覆盖编译器警告选项。某些目录特定的选项（例如，-I指令）仍然保留。

请注意，设置CFLAGS将覆盖其默认值-O2，设置WARNING_CFLAGS将覆盖其默认值（以-Wall -W开头），因此如果您只想将一些警告选项添加到默认选项中，例如，可以通过设置CFLAGS=-O2 -Werror来实现。设置WARNING_CFLAGS在您想删除其默认内容时非常有用（例如，因为您的编译器不接受-Wall作为选项）。目录特定的选项不能从命令行覆盖。

根据您的平台，您可能会遇到一些问题。请检查library/、programs/和tests/中的Makefile，其中包含可手动添加或删除特定平台的选项。您也可以查看< Logistics_information_mbed_org_kb)。

如果您发现您还需要做其他事情，请告诉我们，这样我们就可以将其添加到Mbed TLS知识库中。

CMake

为了在单独的目录中使用CMake构建源代码（推荐），只需在命令行中输入

mkdir /path/to/build_dir && cd /path/to/build_dir
cmake /path/to/mbedtls_source
make

要运行测试，请输入

make test

测试套件需要Perl来构建。如果没有安装Perl，您可能需要禁用测试套件，如下所示

cmake -DENABLE_TESTING=Off /path/to/mbedtls_source

如果您禁用了测试套件但保留程序启用，您仍然可以运行一组更小的测试

programs/test/selftest

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

cmake -DUSE_SHARED_MBEDTLS_LIBRARY=On /path/to/mbedtls_source

在CMake构建系统中提供了许多不同的构建模式。其中大部分对gcc和clang都是可用的，尽管一些是针对特定编译器的。

  • 发布。这会生成默认的代码，在二进制文件中没有不必要的信息。
  • 调试。这会生成调试信息并禁用代码优化。
  • 覆盖。这会在调试信息的基础上生成代码覆盖信息。
  • ASan。这通过AddressSanitizer来对代码进行操作，以检查内存错误。（包括LeakSanitizer，对于gcc和clang的较新版本。）（对于clang的较新版本，此模式还会使用UndefinedSanitizer对未定义行为进行检查。）
  • ASanDbg。与ASan相同，但速度较慢，包含调试信息和更好的堆栈跟踪。
  • MemSan。这通过MemorySanitizer对代码进行操作，以检查未初始化的内存读取。实验性功能，需要在Linux/x86_64上使用较新的clang。
  • MemSanDbg。与MemSan相同，但速度较慢，包含调试信息，更好的堆栈跟踪和源头跟踪。
  • 检查。这激活了编译器依赖优化的警告，并将所有警告视为错误。

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

cmake -D CMAKE_BUILD_TYPE=Debug /path/to/mbedtls_source

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

cmake -LH

请注意，在CMake中，你无法在执行cmake初始调用之后调整编译器或其标志。这意味着CC=your_cc make和make CC=your_cc将不会工作（与CFLAGS和其他变量类似）。这些变量需要在第一次调用cmake时进行调整，例如

CC=your_cc cmake /path/to/mbedtls_source

如果你已经执行了cmake并想要更改这些设置，你需要删除构建目录并重新创建。

请注意，可以就地构建；但这将覆盖提供的Makefiles（如果你希望防止git status将其显示为已修改，请参阅scripts/tmp_ignore_makefiles.sh）。为此，从Mbed TLS源目录中，使用

cmake .
make

如果你想之后更改CC或CFLAGS，你需要删除CMake缓存。可以使用以下命令，使用GNU find完成

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

现在你可以进行所需的更改

CC=your_cc cmake .
make

关于变量，还要注意，在调用cmake时设置CFLAGS时，CFLAGS的值不会覆盖cmake提供的（取决于上面看到的构建模式），它只是附加到其内容上。

Microsoft Visual Studio

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

解决方案文件mbedTLS.sln包含构建库和所有程序所需的所有基本项目。测试文件夹中的文件不会被生成和编译，因为这些文件需要perl环境。但是，programs/test/目录中的自检程序仍然是可用的。

示例程序

我们在programs/目录中包含了大量功能和用途的示例程序。[查看](programs/README.md)。大多数程序只关注单个功能或使用场景，所以当复制代码片段时请牢记这一点。

Mbed TLS 包含了一个详尽的测试套件在 tests/ 目录中，最初需要 Perl 生成测试文件（例如 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/key-exchanges.pl 测试只有一个密钥交换启用的配置的构建。
  • tests/scripts/all.sh 运行上述测试的组合，加上更多测试，以及各种构建选项（如 ASan、完整的 config.h 等）。

我们在 configs/ 目录中提供了一些非标准的配置，专注于特定的使用案例。您可以在 configs/README.txt 中了解更多信息。

Mbed TLS 可移植到许多不同的架构、操作系统和平台。在开始移植之前，您可能会发现以下知识库文章很有用

我们感谢社区提交的 bug 报告和贡献。为了能够集成贡献，我们需要满足一些要求

  • 所有贡献，无论大小，都需要签署一份贡献者许可协议（CLA），才能被接受。这是因为在版权法下，源代码可能属于版权，我们需要您的同意来共享版权所有权。
  • 我们要求贡献符合理编码标准，并且提交前需要进行全面测试。
  • 与任何开源项目一样，贡献将由中国核能项目团队和社区进行审查，可能需要一些修改才能被接受。

为了接受贡献者许可协议（CLA），个人贡献者可以通过创建一个Mbed账号并在此处点击同意在线协议来完成。或者，对于来自公司的贡献，或者不想创建Mbed账号的个人，可以在这里找到一份不同的协议 在这里。根据说明签名并退回给Arm。

贡献

  1. 检查现有问题或开始围绕某个功能想法或错误进行讨论。
  2. 在GitHub上Fork Mbed TLS 仓库以开始更改。通常情况下，您应该以"开发"分支为基础。
  3. 编写一个测试以证明错误已被修复或功能按预期工作。
  4. 发送一个拉取请求，并在合并和发布之前不断与我们交流。贡献可能需要进行一些修改，所以请您与我们合作，以便您的更改被接受。我们将把您的名字列入变更日志：）