Serial Studio 中的 Mbed TLS 3.6.7构建系统、配置方式与 OPC UA 加密栈集成详解【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio本文以 Serial Studio 仓库内 vendored 的 lib/mbedtls/README.md 为主线系统讲解 Mbed TLS 的三大构建系统GNU Make、CMake、Visual Studio、配置机制mbedtls_config.h与scripts/config.py、PSA 密码学 API 的启用方式与移植平台要求并结合本仓库 lib/CMakeLists.txt 与 lib/open62541/CMakeLists.txt 的源码说明这套 C 库是如何以 CMake 子项目形式支撑 Serial Studio 的 OPC UA 安全通道的。读完本文你既能独立编译 Mbed TLS 及其测试套件也能理解它在本仓库中的角色边界只编译库本体、不开启示例程序与测试、静态链接进最终可执行文件。版本与用途仓库里这颗加密基石lib/mbedtls是 Mbed-TLS/mbedtls 上游v3.6.7的完整源码树这一点由机器可读的溯源清单 lib/VERSIONS.json 明确断言version: 3.6.7ref: v3.6.7版本标记同时断言于lib/mbedtls/CMakeLists.txt的project()声明和 lib/mbedtls/ChangeLog注释写明其用途Backs the six OPC UA security policies (spec 0067)即支撑 OPC UA 驱动所需的六个安全策略。这与 lib/mbedtls/CMakeLists.txt 中的project(Mbed TLS ... VERSION 3.6.7)完全吻合。Mbed TLS 本身是 Arm 提供的 C 密码库实现密码学原语含 PSA Cryptography API、X.509 证书操作以及 SSL/TLS 与 DTLS 协议其小代码足迹使其适合嵌入式系统——这正是 Serial Studio 这样一个跨平台遥测应用选择它做静态依赖的理由。从本仓库的构建结构看mbedTLS 是 OPC UA 技术栈mbedTLS open62541的底座lib/open62541/CMakeLists.txt 的注释指出vendored 的 open62541 单文件发行版在发布时已经预定义了UA_ENABLE_ENCRYPTION_MBEDTLS因此所有安全策略直接来自lib/mbedtls而不是目标机器上解析到的任何系统库——OPC UA 驱动的存在性与能力是本构建的属性spec 0067。三个库、三条目标依赖关系与链接顺序README 明确说明Make 与 CMake 构建系统会生成三个库且存在严格的依赖链libmbedcrypto密码学原语层对应 CMake 目标mbedcryptolibmbedx509X.509 证书处理对应目标mbedx509依赖 mbedcryptolibmbedtlsTLS/DTLS 协议层对应目标mbedtls依赖 mbedx509 与 mbedcrypto。由于依赖方向固定部分链接器要求标志按特定顺序出现。例如 GNU 链接器期望-lmbedtls -lmbedx509 -lmbedcrypto上层库在前。在 CMake 侧open62541 目标的写法正是如此lib/open62541/CMakeLists.txt 中target_link_libraries(open62541 PUBLIC mbedtls mbedx509 mbedcrypto)三个目标按依赖序排列。配置mbedtls_config.h 与 config.pyMbed TLS 在大多数系统上开箱即可构建。平台相关的选项与特性开关都集中在配置文件 lib/mbedtls/include/mbedtls/mbedtls_config.h该文件带有完整注释可手工编辑也可以通过 Python 3 脚本scripts/config.py以编程方式修改运行--help查看用法。两个与 Serial Studio 集成直接相关的配置项值得单独说明README 的 PSA 章节MBEDTLS_USE_PSA_CRYPTO激活后X.509 与 TLS 代码将大部分操作经由 PSA 密码学实现README 特别指出TLS 1.3 无论此选项是否开启都主要使用 PSA 密码学MBEDTLS_PSA_CRYPTO_CONFIG允许在不引入对应软件实现代码的前提下启用 PSA 密码机制通常用于配合硬件加速器/安全元件驱动。README 同时声明驱动接口尚未完全稳定应用代码使用 PSA Crypto API的向后兼容会被保留但驱动代码可能在后续小版本中变化。编译器选项则通过常规环境变量CC、CFLAGS在 Make 与 CMake 下设置但注意 CMake 下这类变量只能在首次调用时生效下文详述。工具版本要求README 给出的构建工具清单适用于其自带 makefile 的构建方式工具版本要求用途GNU Make3.82Make 构建C 工具链编译器/链接器/归档器C99官方活跃测试 GCC 5.4、Clang 3.8、Arm Compiler 6、IAR 8、Visual Studio 2017编译库本体Python3.8生成测试代码、集成 PSA 驱动、构建 development 分支Perl任意运行测试、生成开发分支的部分源文件CMake3.10.2CMake 构建时CMake 构建Visual Studio2017VS 构建时Windows 构建Doxygen1.8.11生成文档时make apidoc本地文档另外development 分支与mbedtls-3.6长期支持分支使用 Git 子模块framework 子项目仅在发布 tag 上编译、或消费 zip/tar 发行包时不需要该子模块。development 分支的生成源文件Mbed TLS 源码包含一批由脚本自动生成的文件其内容只取决于 Mbed TLS 源码本身与平台和库配置无关因此不出现在 development 分支中但包含在正式发行包里。生成这些文件需要Perl部分库源文件与 Visual Studio 构建文件Python 3.8及若干包安装命令python3 -m pip install --user -r scripts/basic.requirements.txt如需系统级安装可省略--user宿主机 C 编译器用于生成部分测试数据。脚本查找宿主 C 编译器的优先级顺序是HOSTCC环境变量当CC指向交叉编译器时使用CC环境变量当前路径下的cc可执行文件。README 建议安装多套工具链时在生成文件前显式设置CC或HOSTCC。可用的生成方式包括非交叉编译时任意make目标会自动生成非 Windows 非交叉编译时 CMake 自动生成或显式运行make generated_files、tests/scripts/check-generated-files.sh -uUnix/POSIX、scripts\make_generated_files.batWindows。这一点在 Serial Studio 中有实际体现lib/CMakeLists.txt 在把 mbedTLS 作为子项目引入时强制设置了GEN_FILES OFF——因为 vendored 的树携带的是发行版形态生成文件已就位不需要重复运行生成脚本。GNU Make 构建构建库与示例程序只需要 GNU Make 加一个 C 编译器make # 构建库与示例程序 make check # 构建并运行测试需要 Python 构建、Perl 运行 make no_test # 跳过需要 Python/Perl 的测试构建跳过完整测试后仍可运行更小的自检集programs/test/selftest。Windows 目标有专门变量构建环境为类 Unix如交叉编译或 MSYS shell时设WINDOWS_BUILD1构建环境本身就是 Windows shell如mingw32-make时设WINDOWS1此时部分目标不可用。其他 Make 行为要点环境里设置SHARED会在静态库之外再构建共享库设置DEBUG得到调试构建CFLAGS与LDFLAGS可通过环境变量或 make 命令行覆盖警告选项可单独用WARNING_CFLAGS覆盖目录级选项如-I保留不可覆盖注意CFLAGS的默认值就是-O2WARNING_CFLAGS默认以-Wall -Wextra开头因此只想追加选项时应写成CFLAGS-O2 -Werror这类完整赋值而不是追加针对特定平台的选项可参考library/、programs/、tests/下的 Makefile。README 刻意保持 makefile 功能最小化以降低工具链耦合需要更多功能的用户被建议改用 CMake——这正是 Serial Studio 采用 CMake 路径的原因。CMake 构建README 推荐的独立构建目录流程mkdir /path/to/build_dir cd /path/to/build_dir cmake /path/to/mbedtls_source cmake --build . ctest # 运行测试套件若缺少 Python/Perl可用cmake -DENABLE_TESTINGOff /path/to/mbedtls_source关闭测试套件此时仍可用programs/test/selftest跑小型自检。构建共享库用-DUSE_SHARED_MBEDTLS_LIBRARYOn。CMake 下提供了多种构建模式多数适用于 gcc 与 clang模式说明Release默认二进制中不含多余信息Debug生成调试信息并关闭优化Coverage调试信息之外再生成代码覆盖率信息ASanAddressSanitizer 内存检查新版 gcc/clang 含 LeakSanitizer新版 clang 还叠加 UndefinedSanitizerASanDbgASan 加调试信息更慢、栈回溯更好MemSanMemorySanitizer 检查未初始化内存读实验性需较新 clang 且 Linux/x86_64MemSanDbgMemSan 加调试信息、栈回溯与 origin trackingCheck激活依赖优化的编译器警告并将所有警告视为错误切换模式很简单cmake -D CMAKE_BUILD_TYPEDebug /path/to/mbedtls_sourcecmake -LH可列出全部选项。CMake 的几个易踩坑点README 专门强调首次调用后无法再调整编译器或标志CCyour_cc make在 CMake 项目里不生效必须首次就CCyour_cc cmake ...已配置过则需删除构建目录重来就地构建cmake .make可行但会覆盖仓库中的 makefile可用scripts/tmp_ignore_makefiles.sh让git status不再显示其为修改改CC/CFLAGS后需清理 CMake 缓存README 给出了基于find的清理命令设置CFLAGS不会覆盖 CMake 按构建模式提供的默认内容只是前置拼接。作为依赖消费find_package(MbedTLS)Mbed TLS 提供 package config 文件供其他 CMake 项目作为依赖使用find_package(MbedTLS)若被提示设置MbedTLS_DIR指向${YOUR_MBEDTLS_INSTALL_DIR}/cmake。这会创建三个目标MbedTLS::mbedcrypto加密库、MbedTLS::mbedtlsTLS 库、MbedTLS::mbedx509X.509 库然后可直接add_executable(xyz) target_link_libraries(xyz PUBLIC MbedTLS::mbedtls MbedTLS::mbedcrypto MbedTLS::mbedx509)链接后还会把 Mbed TLS 的包含目录传递给目标PUBLIC/INTERFACE链接库情形下是传递性的。作为 CMake 子项目Serial Studio 的实际集成方式README 最后指出 Mbed TLS 支持被父项目用add_subdirectory()纳入构建且 lib/mbedtls/CMakeLists.txt 中有对应的自检测逻辑当MBEDTLS_AS_SUBPROJECT未显式定义时若CMAKE_CURRENT_SOURCE_DIR不等于CMAKE_SOURCE_DIR就判定为子项目从而自动禁用自身的 install/export 规则。Serial Studio 正是走的这条路。lib/CMakeLists.txt 中的集成块展示了完整的工程化决策if(SS_ENABLE_OPCUA AND (BUILD_COMMERCIAL OR SS_BUILD_TESTS)) set(ENABLE_TESTING OFF CACHE BOOL FORCE) set(ENABLE_PROGRAMS OFF CACHE BOOL FORCE) set(MBEDTLS_FATAL_WARNINGS OFF CACHE BOOL FORCE) set(GEN_FILES OFF CACHE BOOL FORCE) set(USE_STATIC_MBEDTLS_LIBRARY ON CACHE BOOL FORCE) set(USE_SHARED_MBEDTLS_LIBRARY OFF CACHE BOOL FORCE) add_subdirectory(mbedtls) add_subdirectory(open62541) ... endif()逐条对应 README 说明的选项强制先add_subdirectory(mbedtls)再add_subdirectory(open62541)注释说明 open62541 会链接 mbedTLS 的目标顺序不能反ENABLE_TESTING/ENABLE_PROGRAMS关闭vendored 树只携带库本体编译所需内容不含测试与示例程序README 中make check、programs/那套在本仓库用不到USE_STATIC_MBEDTLS_LIBRARY ON与 README 的-DUSE_SHARED_MBEDTLS_LIBRARY选项相反方向取值把三个库静态链进最终可执行文件——这与 open62541 侧为静态链进单一可执行文件的客户端构建的定位一致GEN_FILES OFF跳过生成文件步骤因为消费的是发行版形态的树MBEDTLS_FATAL_WARNINGS OFF 逐目标-w//wlib/CMakeLists.txt 随后遍历mbedtls、mbedx509、mbedcrypto以及3rdparty下独立的everest、p256m目标统一压制第三方警告注释解释这是为了消除-Wundef报告的MBEDTLS_GCC_VERSION未定义这类第三方噪音保持干净构建。还有一处值得注意的构建拓扑target_link_open62541()在无 OPC UA 栈的配置下被定义为空操作lib/CMakeLists.txt即 GPL 配置下即使 SS_BUILD_TESTS 会构建该栈用于单元测试tst_opcua_marshal 需要真实 open62541 来固定其 C 词表与 Qt 之间的接缝也不会把库带进应用本体。本地补丁mbedtls 证书写入器中的 SAN 缓冲区问题虽然 mbedtls 树本身保持上游原样但 vendored 的 open62541 单文件发行版中有一个与 mbedtls API 直接相关的本地补丁记录在 lib/open62541/PATCHES.md上游将 subjectAltName 扩展的临时缓冲区按MBEDTLS_SAN_MAX_LEN * sandeep sandeep每名单固定 64 字节估算涉及mbedtls_x509write_crt_set_subject_alt_name()UA_CreateCertificate使用与mbedtls_x509write_csrSetSubjectAltName()两处当 DNS 名超过约 47 个字符且叠加 URI SAN 后预算溢出ASN.1 反向写入器返回MBEDTLS_ERR_ASN1_BUF_TOO_SMALL证书生成报 Setting subject alternative name failed。该问题在 macOS CI 上以 67 字符主机名sjc22-bm210-uuid-mac.local批量暴露所有安全通道集成测试失败而短主机名机器通过修复是在两处分配中加入实际名称长度buflen it-node.hostlenCSR 变体则遍历it-buf.len保留原每名单的冗余量以覆盖 ASN.1 tag/length 开销。这个补丁是理解为何版本必须钉死的最佳案例lib/CMakeLists.txt 的注释解释 mbedTLS 故意固定在 3.6 LTS 线——open62541 的 crypto 插件用MBEDTLS_VERSION_NUMBER检查保护其 API 使用且止步于 3.x而 4.x 是破坏性的 PSA-only 发布。升级 mbedTLS 时须同步处理 PATCHES.md 中记录的补丁重放。测试体系Mbed TLS 自带一套完备的测试体系README 的 Tests 一节tests/下的测试套件先用 Python 从function 文件如suites/test_suite_mpi.function包含测试函数与data 文件如suites/test_suite_mpi.data以参数形式给出测试用例生成test_suite_*.c这类源文件在装有 OpenSSL可选 GnuTLS的 Unix 机器上还有互操作脚本tests/ssl-opt.shTLS 选项集成测试renegotiation、resumption 等、tests/compat.sh每条密码套件与其他实现的互操作、tests/scripts/test-ref-configs.pl多种缩减配置下构建、tests/scripts/depends.py单曲线/单密钥交换/单哈希/单密码/单 pkalg 的配置矩阵、tests/scripts/all.sh组合以上并叠加 ASan、完整mbedtls_config.h等构建选项。如前所述Serial Studio 的构建有意关闭了这套测试ENABLE_TESTING OFFmbedtls 自身的正确性由上游 CI 负责本仓库的验证落在 OPC UA 侧的单元测试如app/tests/tst_opcua_security.cpp、app/tests/tst_opcua_subscriptions.cpp等之上。移植平台要求README 列出 Mbed TLS 对 C99 之外的平台要求现代架构基本都满足字节必须是 8 位全零位必须是空指针的有效表示有符号整数必须采用二进制补码int与size_t至少 32 位uint8_t、uint16_t、uint32_t及对应符号类型必须可用不支持混合字节序平台SIZE_MAX至少不小于INT_MAX与UINT_MAX。Serial Studio 的跨平台Linux/macOS/Windowsx86_64 与 arm64目标恰好都满足这些约束这也是静态 vendored 一棵 C 树方案可行的前提之一。PSA 密码学 API 概览README 用相当篇幅介绍了 PSAPlatform Security ArchitectureAPI 设计目标包括区分调用方内存与库内部内存允许库实现在隔离空间内调用可以是直接函数调用也可以是 RPC隐藏内部数据结构可在构建期或运行期替换实现例如利用硬件加速器所有密钥访问都通过密钥标识符对应用透明地支持外部加密处理器接口以算法 agility 为导向易用且难以误用。在 Mbed TLS 中的实现覆盖了大部分非全部算法。X.509 与 TLS 代码可经由MBEDTLS_USE_PSA_CRYPTO切换到 PSA 路径TLS 1.3 默认如此。PSA 驱动支持加密加速器、安全元件与随机数生成器推荐同时启用MBEDTLS_USE_PSA_CRYPTO与MBEDTLS_PSA_CRYPTO_CONFIG使 X.509/TLS 代码走 PSA 驱动而非内置软件实现。README 明确声明驱动接口仍在完善中可能随小版本变化。文档生成与示例程序生成贴合当前编译配置的本地 HTML 文档README 的 Documentation 一节安装 Doxygen1.8.11运行make apidoc浏览apidoc/index.html或apidoc/modules.html。其他文档渠道可参考 lib/mbedtls/SUPPORT.md。示例程序方面上游在programs/目录提供了覆盖大量特性的样例本 vendored 树未携带README 提醒这些程序的目标是演示特性、代码需自行改造才能用于真实应用。许可与第三方代码README 的 License 一节除个别文件另有说明外Mbed TLS 文件以Apache-2.0 OR GPL-2.0-or-later双重许可提供全文见 lib/mbedtls/LICENSE。3rdparty/目录包含3rdparty/everest/源自 Project EverestApache 2.03rdparty/p256-m/p256-m/源自 p256-m 仓库在上游为 Apache 2.0在 Mbed TLS 中经作者许可以 Apache-2.0 OR GPL-2.0-or-later 双重许可分发。这与 Serial Studio 侧的处理相呼应lib 层的构建胶水如 lib/CMakeLists.txt采用 GPL-3.0-or-later OR 商业许可的双许可头而 mbedTLS 自身作为 Apache-2.0 可选的依赖保持独立的许可边界。安全响应与贡献README 的 Contact/Contributing 部分给出两条路径安全漏洞应通过安全邮件列表报告详见 lib/mbedtls/SECURITY.md普通 bug 与特性请求走上游 issue贡献流程见 lib/mbedtls/CONTRIBUTING.md。分支模型development 分支与 3.6 LTS 线参见 lib/mbedtls/BRANCHES.md。小结lib/mbedtls/README.md描述的是一套成熟密码库的标准工程实践单一mbedtls_config.h配置入口、三套等价构建系统、三层库的严格依赖顺序、按构建模式切换的 sanitizer 矩阵、以及find_package与add_subdirectory两种消费姿势。Serial Studio 从中选取了最贴合静态链进单一桌面可执行文件的一条路径——CMake 子项目 强制静态库 关闭测试/示例/生成文件 逐目标压制警告——并与预编译出 mbedTLS 加密插件的 open62541 1.5.7 单文件发行版配对共同构成 OPC UA 驱动的六个安全策略实现。版本钉死在 3.6.7、补丁边界记录在 lib/open62541/PATCHES.md、溯源元数据固化在 lib/VERSIONS.json使这棵 vendored 树是否最新、被改过什么这两个问题始终可以被机械地回答。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
