wolfSSL/wolfssl

# wolfSSL 嵌入式 SSL/TLS 库 [wolfSSL 嵌入式 SSL 库](https://www.wolfssl.com/products/wolfssl/)（原名 CyaSSL）是一个轻量级的 SSL/TLS 库，使用 ANSI C 编写，专为嵌入式、RTOS 和资源受限环境设计——这主要归功于其小巧的体积、速度和功能集。由于免版税的定价和优秀的跨平台支持，它也被广泛用于标准操作环境。wolfSSL 支持包括最新的 [TLS 1.3](https://www.wolfssl.com/tls13) 和 DTLS 1.3 在内的行业标准，体积比 OpenSSL 小 20 倍，并提供先进的加密算法，如 ChaCha20、Curve25519、BLAKE2b/BLAKE2s 和后量子 TLS 1.3 组。用户基准测试和反馈报告显示，使用 wolfSSL 比 OpenSSL 性能显著更好。 wolfSSL 由 wolfCrypt 加密库提供支持。两个版本的 wolfCrypt 已通过 FIPS 140-2 验证（证书 #2425 和证书 #3389）。FIPS 140-3 验证（证书 #4718）。欲了解更多信息，请访问 [wolfCrypt FIPS FAQ](https://www.wolfssl.com/license/fips/) 或联系 fips@wolfssl.com。 ## 为什么选择 wolfSSL？ 选择 wolfSSL 作为您的嵌入式、桌面、移动或企业 SSL/TLS 解决方案有很多理由。其中最主要的理由包括体积（典型内存占用范围从 20-100 kB）、支持最新标准（SSL 3.0、TLS 1.0、TLS 1.1、TLS 1.2、TLS 1.3、DTLS 1.0、DTLS 1.2 和 DTLS 1.3）、当前和先进的加密套件支持（包括流加密）、多平台支持、免版税，以及提供 OpenSSL 兼容 API 以便轻松移植到之前使用 OpenSSL 包的现有应用程序中。有关完整的功能列表，请参阅 wolfSSL 手册的 [第 4 章](https://www.wolfssl.com/docs/wolfssl-manual/ch4/)。 ## 注意事项，请阅读 ### 注意 1 从 3.6.6 版本开始，wolfSSL 不再默认启用 SSLv3。默认情况下，wolfSSL 禁用使用 PSK、RSA 或 ECDH 且不含临时密钥交换的静态密钥加密套件。相反，wolfSSL 启用通过临时 Diffie-Hellman (DH) 或椭圆曲线 (ECC) 密钥交换提供完美前向保密 (PFS) 的加密套件，这两者默认均启用。 如果您需要支持需要静态密钥加密套件的旧系统，可以使用以下定义之一启用它们： * `WOLFSSL_STATIC_DH` * `WOLFSSL_STATIC_RSA` * `WOLFSSL_STATIC_PSK` **重要提示：** 静态密钥加密套件通过消除完美前向保密来降低安全性。这些加密套件对所有会话密钥交换重用相同的长期私钥。相比之下，启用 PFS 的加密套件（wolfSSL 默认设置）为每个会话生成一个新的临时密钥，确保泄露长期密钥无法解密过去的会话。 在编译 `ssl.c` 时，如果没有可用的加密套件，wolfSSL 现在将发出编译器错误。如果您希望在这种情况下移除此错误，可以通过定义 `WOLFSSL_ALLOW_NO_SUITES` 来实现，即您不使用 TLS 加密套件。 ### AES CryptoCB 密钥导入支持 wolfSSL 通过 CryptoCB 支持硬件加速的 AES 操作。 当定义了 `WOLF_CRYPTO_CB_AES_SETKEY` 时，wolfSSL 会在 AES 密钥设置期间调用 CryptoCB 回调。回调行为决定模式： **如果回调返回 0（成功）：** - 密钥被导入到安全元件/HSM - 密钥不会被复制到 wolfSSL RAM（真正的密钥隔离） - 不生成 GCM 表（完全硬件卸载） - 所有后续 AES 操作通过 CryptoCB 路由 **如果回调返回 CRYPTOCB_UNAVAILABLE：** - SE 不支持密钥导入 - 使用普通软件 AES 路径 - 密钥被复制到 devKey 以进行 CryptoCB 加密/解密加速 此功能在嵌入式平台上启用 TLS 1.3 流量密钥保护，在这些平台上对称密钥绝不能存在于主 RAM 中。 启用方式：`CPPFLAGS="-DWOLF_CRYPTO_CB_AES_SETKEY -DWOLF_CRYPTO_CB_FREE"` ### 注意 2 wolfSSL 采用与 OpenSSL 不同的证书验证方法。客户端的默认策略是验证服务器，这意味着如果您不加载 CA 来验证服务器，您将收到连接错误，即没有签名者错误以确认失败 (-188)。 如果您想模仿 OpenSSL 的行为，即使验证服务器失败也让 `SSL_connect` 成功并降低安全性，可以通过调用以下代码来实现： ``` wolfSSL_CTX_set_verify(ctx, WOLFSSL_VERIFY_NONE, NULL); ``` 在调用 `wolfSSL_new();` 之前。但不建议这样做。 ### 注意 3 当 wolfSSL 使用 `--enable-opensslextra` (`OPENSSL_EXTRA`) 或宏 `NO_OLD_SHA_NAMES` 构建时，枚举值 SHA、SHA256、SHA384、SHA512 将不再可用。这些名称被映射到 OpenSSL API 用于单次调用哈希函数。应改用 `WC_SHA`、`WC_SHA256`、`WC_SHA384` 和 `WC_SHA512` 作为枚举名称。 # wolfSSL 5.8.4 版本 (2025 年 11 月 20 日) 5.8.4 版本是根据 wolfSSL 的开发和 QA 流程（见下方链接）开发的，并成功通过了质量标准。 https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance 注意：* --enable-heapmath 已弃用 * MD5 现在默认禁用 PR 代表 Pull Request，PR 引用 GitHub pull request 编号，其中添加了代码更改。 ## 漏洞 * [低危 CVE-2025-12888] 由于编译器优化和 CPU 架构限制（特别是基于 Xtensa 的 ESP32 芯片）引起的时间侧信道，导致 X25519 常量时间加密实现中存在漏洞。如果针对 Xtensa，建议使用 X25519 的低内存实现，这现在已成为 Xtensa 的默认设置。感谢 Adrian Cinal 的报告。已在 PR 9275 中修复。 * [中危 CVE-2025-11936] 由于恶意 TLS 1.3 ClientHello 消息中具有相同组的多个 KeyShareEntry 导致的内存泄漏，可能引起 DoS 漏洞。这影响在服务器端运行 TLS 1.3 的 wolfSSL 用户。感谢来自浦项科技大学 (POSTECH) 的 Jaehun Lee 和 Kyungmin Bae 的报告。已在 PR 9117 中修复。 * [低危 CVE-2025-11935] 在 TLS 1.3 握手期间，具有 PFS（完美前向保密）的 PSK 降级为没有 PFS 的 PSK。如果客户端发送的 ClientHello 包含密钥共享扩展，而服务器响应的 ServerHello 不包含密钥共享扩展，则连接之前会继续而不使用 PFS。感谢来自浦项科技大学 (POSTECH) 的 Jaehun Lee 的报告。已在 PR 9112 中修复。 * [低危 CVE-2025-11934] TLS 1.3 握手期间签名算法从 ECDSA P521 降级到 P256。当客户端发送 ECDSA P521 作为支持的签名算法时，服务器之前可能响应 ECDSA P256 作为接受的签名算法，连接将继续使用 ECDSA P256。感谢来自浦项科技大学 (POSTECH) 的 Jaehun Lee 的报告。已在 PR 9113 中修复。 * [低危 CVE-2025-11933] wolfSSL TLS 1.3 CKS 扩展解析中的 DoS 漏洞。以前重复的 CKS 扩展未被拒绝，导致在处理 ClientHello 时可能发生内存泄漏。感谢来自浦项科技大学 (POSTECH) 的 Jaehun Lee 的报告。已在 PR 9132 中修复。 * [低危 CVE-2025-11931] XChaCha20-Poly1305 解密中的整数下溢导致越界访问。此问题仅在调用函数 wc_XChaCha20Poly1305_Decrypt() 时触发，该函数不用于 TLS 连接，仅来自应用程序的直接调用。感谢来自 Aisle Research 的 Luigino Camastra 的报告。已在 PR 9223 中修复。 * [低危 CVE-2025-11932] PSK Binder 验证中的时间侧信道。服务器之前使用非常量时间方法验证 TLS 1.3 PSK binder，这可能会泄露有关 PSK binder 的信息。感谢来自 Aisle Research 的 Luigino Camastra 的报告。已在 PR 9223 中修复。 * [低危 CVE-2025-12889] 在 TLS 1.2 连接中，客户端可以使用任何摘要，特别是较弱的摘要，而不是 CertificateRequest 中的摘要。感谢来自浦项科技大学 (POSTECH) 的 Jaehun Lee 的报告。已在 PR 9395 中修复 * [低危 CVE-2025-13912] 使用 Clang 编译器时，各种优化级别或标志可能导致非常量时间的编译代码。wolfSSL 中函数的汇编实现未受影响。该报告是针对 Clang 版本 18 进行的，但显示在使用 Clang 14 和 Clang 20 的优化级别时也存在类似的时间变化。 在以下架构中，当使用特定的编译器标志或优化级别时，预期的常量时间函数被发现存在潜在的时间变化。 AArch64：使用 O3、Ofast 或 --enable-nontrivial-unswitch 与 O1/O2 标志，会导致 sp_read_radix、sp_div_2_mod_ct 和 sp_addmod_ct 的软件实现可能出现时间变化。使用 O3、O2、Ofast、Os 或 Oz 与 --unroll-force-peel-count=50 会导致 wc_AesGcmDecrypt 可能出现时间变化。 RISC-V：TLS HMAC update/final 操作、RSA unpad 操作和 DH 密钥对生成（使用 O1、O2、O3、Ofast、Oz 或 Os）。wc_AesGcmDecrypt 和 wc_Chacha_Process（使用 O1、O2、O3、Os 或 Ofast）。以及 SP 软件操作 sp_div_2_mod_ct 和 sp_addmod_ct（使用 O3 或 Ofast）。 X86_64：TLS HMAC update/final 操作和用于验证 TLS MAC 的 TimingVerifyPad（使用 --fast-isel 或 --x86-cmov-converter-force-all 编译标志）。RSA unpad 操作、ECC mulmod 和 wc_Chacha_Process（使用 --x86-cmov-converter-force-all 标志）。DH 密钥协商、sp_div_2_mod_ct 和 sp_addmod_ct（使用 O1、O2、O3、Os 或 Ofast）。wc_AesGcmDecrypt（使用编译器标志 O2、O3、Os、Ofast、Oz --x86-cmov-converter-force-all | --unroll-force-peel-count=50，或 O1 --x86-cmov-converter-force-all）。 感谢来自马克斯·普朗克安全与隐私研究所 (MPI-SP) 的 Jing Liu、Zhiyuan Zhang、LUCÍA MARTÍNEZ GAVIER、Gilles Barthe、Marcel Böhme 的报告。已在 PR 9148 中修复。 ## 新功能 * 新增 ML-KEM / ML-DSA API 和 seed/import PKCS8 支持；为 ML-KEM/ML-DSA 添加了 _new/_delete API。(PR 9039, 9000, 9049) * 初步 wolfCrypt FreeBSD 内核模块支持 (PR 9392) * 扩展 PKCS7/CMS 功能：解码 SymmetricKeyPackage / OneSymmetricKey，添加 wc_PKCS7_GetEnvelopedDataKariRid，并允许在未设置 AES keywrap 的情况下构建 PKCS7。(PR 9018, 9029, 9032) * 添加自定义 AES key wrap/unwrap 回调和 crypto callback copy/free 操作。(PR 9002, 9309) * 添加对 ClientHello 中 certificate_authorities 扩展的支持以及证书管理器 CA 类型选择/卸载。(PR 9209, 9046) * 大规模扩展 Rust 包装器模块：random、aes、rsa、ecc、dh、sha、hmac、cmac、ed25519/ed448、pbkdf2/PKCS#12、kdf/prf、SRTP KDFs 和条件编译选项。(PR 9191, 9212, 9273, 9306, 9320, 9328, 9368, 9389, 9357, 9433) * Rust：支持可选的 heap 和 dev_id 参数，并根据 C 构建选项启用条件编译。(PR 9407, 9433) * STM32 修复（基准测试和平台修复）和 PSoC6 硬件加速补充。(PR 9228, 9256, 9185) * STM32U5 增加了对 SAES 和 DHUK 的支持。(PR 9087) * 添加 --enable-curl=tiny 选项，用于与 cURL 一起使用时构建更小的版本。(PR 9174) ## 改进 / 优化 * 回测试修复和扩展：TLS 1.3/1.2 测试、ARDUINO 示例、libssh2 测试、hostap 工作流和夜间测试改进。(PR 9096, 9141, 9091, 9122, 9388) * 改进测试排序和 CI 测试稳定性（随机测试运行顺序更改、FIPS 测试修复）。(PR 9204, 9257) * 文档和 readme 修复、文档字符串更新、AsconAEAD 注释位置和示例证书更新。(PR 9131, 9293, 9262, 9429) * 更新 GPL 例外列表（GPLv2 和 GPLv3 例外更新：添加 Fetchmail 和 OpenVPN）。(PR 9398, 9413) * 引入 WOLFSSL_DEBUG_CERTS 和额外的调试/日志细化。(PR 8902, 9055) * 扩展 crypto-callback 支持（SHA 系列、HKDF、SHA-224、sha512_family 摘要选择）并改进仅加密构建案例。(PR 9070, 9252, 9271, 9100, 9194) * AES 和硬件卸载改进，包括 PKCS11 驱动程序中的 AES-CTR 支持和 AES ECB 卸载大小修复。(PR 9277, 9364) * ESP32：PSRAM 分配器支持和 ESP-IDF v6/v5 的 SHA HW 修复。(PR 8987, 9225, 9264) * Renesas FSP / RA 示例更新和安全模块 TLS 上下文改进。(PR 9047, 9010, 9158, 9150) * 广泛的 configure/CMake/Autotools 工作流改进（Apple 选项跟踪、Watcom 固定、Debian 打包、ESP-IDF 固定）。(PR 9037, 9167, 9161, 9264) * 针对 RISC-V 和 PPC32 的新汇编内省/性能辅助工具；基准测试增强（周期计数）。(PR 9101, 9317) * 更新 SGX 构建以使用汇编优化。(PR 8463, 9138) * 使用 Fil-C 编译器版本 0.674 进行测试 (PR 9396) * 小堆栈代码的重构和压缩 (PR 9153) ## 错误修复 * 移除了在定义宏 WOLFSSL_USE_POPEN_HOST 且未定义 HAVE_GETADDRINFO，同时设置宏 HAVE_HTTP_CLIENT 时使用 popen 的测试功能。当在此特定构建下调用 API wolfSSL_BIO_new_connect() 时，使用 popen 可能存在易受攻击的行为。此确切的构建配置仅用于 QEMU 测试，并未通过任何 autoconf/cmake 标志启用。感谢 linraymond2006 的报告。(PR 9038) * 修复了 C# 包装器 Ed25519 在使用 API Ed25519ImportPublic 导入原始公钥时可能崩溃和堆覆盖的问题。这是 C# 包装器中的一个损坏的 API，使用时会崩溃。感谢来自 Aisle Research 的 Luigino Camastra 的错误报告。(PR 9291) * Coverity、cppcheck、MISRA、clang-tidy、ZeroPath 和其他静态分析驱动的代码库修复。(PR 9006, 9078, 9068, 9265, 9324) * TLS 1.2/DTLS 改进：客户端消息顺序检查、DTLS cookie/交换和重放保护、更好的 DTLS 早期数据处理。(PR 9387, 9253, 9205, 9367) * 改进 X.509 和证书处理：允许 Basic Constraints 中更大的 pathLen、恢复 ECH 的内部服务器名称、重试证书候选链。(PR 8890, 9234, 8692) * Sniffer 鲁棒性：修复无限递归、更好地处理 OOO appData 和部分重叠以及改进的重传检测。(PR 9051, 9106, 9140, 9094) * 大量 linuxkm（内核模式）修复、重定位/PIE 标准化和多次迭代中的 FIPS 相关构建调整。(PR 9025, 9035, 9067, 9111, 9121) * ML-KEM/Kyber 和 ML-DSA 的越界和 seed-import 正确性修复；多个 ML 相关的安全修复。(PR 9142, 9105, 9439) * 避免未初始化变量和 GCC 警告；修复了一些未定义移位/溢出问题。(PR 9020, 9372, 9195) * X509 验证中的内存和泄漏修复以及 WOLFSSL_NO_MALLOC 使用的各种结构大小修复。(PR 9258, 9036) * 修复 RSA / 签名 / verify-only 警告，允许在使用 WOLFSSL_RSA_VERIFY_ONLY 时使用 WOLFSSL_NO_CT_OPS，以及使用 const 的 API 清理。(PR 9031, 9263) 有关其他漏洞信息，请访问漏洞页面： https://www.wolfssl.com/docs/security-vulnerabilities/ 有关构建说明，请参阅 INSTALL 文件。 更多信息可在以下网址找到：https://wolfssl.com/wolfSSL/Docs.html # 资源 [wolfSSL 网站](https://www.wolfssl.com/) [wolfSSL Wiki](https://github.com/wolfSSL/wolfssl/wiki) [FIPS 140-2/140-3 FAQ](https://wolfssl.com/license/fips) [wolfSSL 文档](https://wolfssl.com/wolfSSL/Docs.html) [wolfSSL 手册](https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-toc.html) [wolfSSL API 参考](https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-17-wolfssl-api-reference.html) [wolfCrypt API 参考](https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-18-wolfcrypt-api-reference.html) [TLS 1.3](https://www.wolfssl.com/docs/tls13/) [wolfSSL 漏洞](https://www.wolfssl.com/docs/security-vulnerabilities/) [更多 wolfSSL 示例](https://github.com/wolfssl/wolfssl-examples) # 目录结构 ``` ├── certs [Certificates used in tests and examples] ├── cmake [Cmake build utilities] ├── debian [Debian packaging files] ├── doc [Documentation for wolfSSL (Doxygen)] ├── Docker [Prebuilt Docker environments] ├── examples [wolfSSL examples] │   ├── asn1 [ASN.1 printing example] │   ├── async [Asynchronous Cryptography example] │   ├── benchmark [TLS benchmark example] │   ├── client [Client example] │   ├── configs [Example build configurations] │   ├── echoclient [Echoclient example] │   ├── echoserver [Echoserver example] │   ├── pem [Example for convert between PEM and DER] │   ├── sctp [Servers and clients that demonstrate wolfSSL's DTLS-SCTP support] │   └── server [Server example] ├── IDE [Contains example projects for various development environments] ├── linuxkm [Linux Kernel Module implementation] ├── m4 [Autotools utilities] ├── mcapi [wolfSSL MPLAB X Project Files] ├── mplabx [wolfSSL MPLAB X Project Files] ├── mqx [wolfSSL Freescale CodeWarrior Project Files] ├── rpm [RPM packaging metadata] ├── RTOS │   └── nuttx [Port of wolfSSL for NuttX] ├── scripts [Testing scripts] ├── src [wolfSSL source code] ├── sslSniffer [wolfSSL sniffer can be used to passively sniff SSL traffic] ├── support [Contains the pkg-config file] ├── tests [Unit and configuration testing] ├── testsuite [Test application that orchestrates tests] ├── tirtos [Port of wolfSSL for TI RTOS] ├── wolfcrypt [The wolfCrypt component] │   ├── benchmark [Cryptography benchmarking application] │   ├── src [wolfCrypt source code] │   │   └── port [Supported hardware acceleration ports] │   └── test [Cryptography testing application] ├── wolfssl [Header files] │   ├── openssl [Compatibility layer headers] │   └── wolfcrypt [Header files] ├── wrapper [wolfSSL language wrappers] └── zephyr [Port of wolfSSL for Zephyr RTOS] ```

标签：ANSI C, ChaCha20, Curve25519, DTLS 1.3, FIPS 140-2, FIPS 140-3, HTTPS, IoT安全, LangChain, OpenSSL兼容, RTOS, SSL/TLS, TLS 1.3, wolfCrypt, wolfSSL, 加密库, 后量子密码学, 客户端加密, 客户端加密, 客户端加密, 密码学, 嵌入式安全, 底层编程, 开源, 手动系统调用, 数据传输加密, 物联网, 移动互联网, 网络安全, 网络安全库, 轻量级, 隐私保护