wolfSSL 嵌入式 SSL/TLS 库

wolfSSL 嵌入式 SSL 库（前身为 CyaSSL）是一款采用 ANSI C 编写的轻量级 SSL/TLS 库，主要面向嵌入式、实时操作系统（RTOS）及资源受限环境。这得益于其小巧的体积、高效的速度和丰富的功能集。同时，由于其免版税的定价策略和出色的跨平台支持，它也广泛应用于标准操作系统环境。wolfSSL 支持包括当前最新的 TLS 1.3 和 DTLS 1.3 在内的行业标准，体积仅为 OpenSSL 的二十分之一，并提供如 ChaCha20、Curve25519、Blake2b 以及后量子 TLS 1.3 组等先进密码算法。用户基准测试和反馈报告显示，使用 wolfSSL 相比 OpenSSL 能获得显著的性能提升。

wolfSSL 由 wolfCrypt 加密库提供支持。wolfCrypt 的两个版本已通过 FIPS 140-2 认证（证书编号 #2425 和 #3389）。FIPS 140-3 认证正在进行中。如需更多信息，请访问 wolfCrypt 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 章。

注意事项，请阅读

注意 1

自 3.6.6 版本起，wolfSSL 默认不再启用 SSLv3。wolfSSL 也不再支持使用 PSK、RSA 或 ECDH 的静态密钥密码套件。这意味着如果您计划使用 TLS 密码套件，必须启用 DH（DH 默认开启），或启用 ECC（ECC 默认开启），或者必须通过以下一个或多个宏定义来启用静态密钥密码套件：

WOLFSSL_STATIC_DH
WOLFSSL_STATIC_RSA
WOLFSSL_STATIC_PSK

尽管静态密钥密码套件已被弃用，并将从未来的 TLS 版本中移除。它们还会通过移除 PFS 来降低您的安全性。

编译 ssl.c 时，如果没有可用的密码套件，wolfSSL 现在会发出编译器错误。如果您希望（例如，您不使用 TLS 密码套件），可以通过定义 WOLFSSL_ALLOW_NO_SUITES 来消除此错误。

注意 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.7.2（2024 年 7 月 8 日）

版本 5.7.2 是根据 wolfSSL 的开发和 QA 流程（见下方链接）开发的，并成功通过了质量标准。 https://www.wolfssl.com/about/wolfssl-software-development-process-quality-assurance

注意：* --enable-heapmath 已被弃用，将于 2024 年底移除

漏洞

• [中等] CVE-2024-1544 在 5.6.6 版本之前的 wolfSSL 中，调用 wc_ecc_sign_hash 可能存在 ECDSA 随机数侧信道攻击。生成 ECDSA 随机数 k 时，会采样一个随机数 r，然后通过模 n（其中 n 是椭圆曲线的阶）的模约化对该随机性进行截断。通过控制流泄露的侧信道分析除法过程，会揭示 k 的最高有效位存在偏差。根据曲线的不同，这种偏差可能微不足道，也可能足够显著，足以通过格规约方法重构 k。感谢 Luca Wilke、Florian Sieck 和 Thomas Eisenbarth（吕贝克大学）报告此漏洞。详细信息将发表在 CCS 24 的会议论文集中。 已修复 https://github.com/wolfSSL/wolfssl/pull/7020

• [中等] CVE-2024-5288 添加了一项私钥盲化操作（通过定义宏 WOLFSSL_BLIND_PRIVATE_KEY 启用），以缓解 ECC 操作中潜在的行锤攻击。如果在恶意用户可能获得设备精细控制权并实施行锤式攻击的环境中执行 ECC 私钥操作，建议更新所使用的 wolfSSL 版本，并在构建时定义 WOLFSSL_BLIND_PRIVATE_KEY。感谢 Kemal Derya、M. Caner Tol、Berk Sunar 的报告（伍斯特理工学院 Vernam 应用密码学与网络安全实验室） 已在 GitHub 拉取请求中修复 https://github.com/wolfSSL/wolfssl/pull/7416

• [低] 当直接使用 wolfSSL API 解析提供的恶意构造证书（不在 TLS 连接中）时，具有过多扩展数量的证书可能导致潜在的 DoS。wolfSSL 在 TLS 握手期间存在现有的健全性检查，可缓解此问题。感谢 Bing Shi 的报告。 已在 GitHub 拉取请求中修复 https://github.com/wolfSSL/wolfssl/pull/7597

• [低] CVE-2024-5991 在 MatchDomainName() 函数中，输入参数 str 被视为以 NULL 结尾的字符串，尽管它是用户提供且未经检查的。具体而言，OpenSSL 兼容函数 X509_check_host() 接收一个指针和长度进行检查，并不要求其以 NULL 结尾。虽然不使用以 NULL 结尾的字符串进行调用非常罕见，但技术上仍是允许的。如果调用者尝试对非 NULL 终止的缓冲区进行名称检查，代码会读取超出输入数组边界的内容，直到找到 NULL 终止符。 已在 GitHub 拉取请求中修复 https://github.com/wolfSSL/wolfssl/pull/7604

• [中等] CVE-2024-5814 恶意的 TLS1.2 服务器可以迫使具有降级能力的 TLS1.3 客户端使用其未同意的密码套件，并建立成功的连接。这是因为，在从 TLS 1.3 降级时，客户端除了扩展之外，会跳过对服务器 hello 的完整解析。 已在 GitHub 拉取请求中修复 https://github.com/wolfSSL/wolfssl/pull/7619

• [中等] 当接收到长度为 0 的特制响应时，OCSP 装订版本 2 的响应验证会被绕过。此问题通过内部测试发现。 已在 GitHub 拉取请求中修复 https://github.com/wolfSSL/wolfssl/pull/7702

• [中等] TLS 连接尝试重试时，OCSP 装订版本 2 存在吊销绕过问题。已吊销的 CA 证书可能会被错误地加载到受信任签名者列表中，并在重复的连接尝试中使用。此问题通过内部测试发现。 已在 GitHub 拉取请求中修复 https://github.com/wolfSSL/wolfssl/pull/7702

新功能新增

• 新增 Dilithium/ML-DSA：实现 ML-DSA-44/65/87（PR 7622）
• AES RISC-V 64 位汇编：ECB/CBC/CTR/GCM/CCM（PR 7569）
• 新增对 AES 加密的 CUDA 支持（PR 7436）
• 新增对 gRPC 的支持（PR 7445）
• 新增函数 wc_RsaPrivateKeyDecodeRaw，用于导入原始 RSA 私钥（PR 7608）
• 新增 SHA-3 的加密回调（PR 7670）
• 支持 Infineon Modus Toolbox 与 wolfSSL 配合使用（PR 7369）
• 允许用户通过调用 wolfSSL_SendUserCanceled 发送 user_canceled 告警（PR 7590）
• C# 包装器新增 SNI 支持（PR 7610）
• Linux 内核模块新增量子安全算法支持（PR 7574）
• 新增对 NIST 800-56C Option 1 KDF 的支持，使用宏 WC_KDF_NIST_SP_800_56C（PR 7589）
• 新增 AES-XTS 流模式，并支持硬件加速和内核模块使用（PR 7522、7560、7424）
• PlatformIO FreeRTOS 支持 ESP 构建，并新增基准测试和测试示例应用程序（PR 7528、7413、7559、7542）

增强与优化

• 扩展 STM32 AES 硬件加速支持，以用于 STM32H5（PR 7578）
• 调整 wc_xmss 和 wc_lms 设置，以支持与 wolfBoot 配合使用（PR 7393）
• 为 autotools 构建新增 --enable-rpk 选项，用于启用原始公钥支持（PR 7379）
• 新增 SHA-3 Thumb2、ARM32 汇编实现（PR 7667）
• 改进 RSA 填充，以公开 Pad/Unpad API（PR 7612）
• 为支持 socat 版本 1.8.0.0 进行更新和 API 新增（PR 7594）
• cmake 构建改进，扩展 SINGLE_THREADED 和后量子算法的构建选项，调整 options.h 文件的生成，并使用“yes;no”布尔值代替字符串（PR 7611、7546、7479、7480、7380）
• 改进 Renesas RZ 支持（PR 7474）
• 改进用于后量子密钥的双算法证书（PR 7286）
• 新增 wolfSSL_SessionIsSetup，以便用户检查服务器是否已发送会话票据（PR 7430）
• hostap 更新：为 EAP-FAST 实现 PAC，并在 TLS 版本更改时过滤密码套件列表（PR 7446）
• 更改主题名称比较方式，以匹配不同大小写（PR 7420）
• 支持使用 PSK 时的 DTLS 1.3 降级（PR 7367）
• 更新静态内存构建，以使用更通用的内存池（PR 7418）
• 提高 Kyber C 实现的性能（PR 7654）
• 支持无 malloc 的 ECC_CACHE_CURVE（PR 7490）
• 新增配置选项 --enable-debug-trace-errcodes（宏 WOLFSSL_DEBUG_TRACE_ERROR_CODES），可启用更详细的错误代码值调试跟踪（PR 7634）
• 增强 wc_MakeRsaKey 和 wc_RsaKeyToDer，使其可与 WOLFSSL_NO_MALLOC 配合使用（PR 7362）
• 改进 ChaCha20 和 Poly1305 ASM 的汇编实现，以用于 MSVC（PR 7319）
• Cortex-M 内联汇编标签附加唯一编号（PR 7649）
• 为 TLS <= 1.2 新增密钥日志回调，通过宏 HAVE_SECRET_CALLBACK 启用（PR 7372）
• 将 wc_RNG_DRBG_Reseed() 设为公开的 wolfCrypt API（PR 7386）
• 启用 DES3 支持，但不包含 DES3 密码套件。要重新启用 DES3 密码套件，请使用配置标志 --enable-des3-tls-suites（PR 7315）
• 新增最新 nginx（1.25.5）所需的存根（PR 7449）
• 新增通过函数 wc_ecc_ctx_set_own_salt 使用自定义盐的选项（PR 7552）
• 新增适用于 Windows 的 PQ 文件（PR 7419）
• 静态内存功能增强，新增全局堆提示选项（PR 7478）以及精简或调试设置的构建选项，可通过 --enable-staticmemory=small 或 --enable-staticmemory=debug 启用（PR 7597）
• 更新 --enable-jni 以定义 wolfJSSE 的 SESSION_CERTS（PR 7557）
• 在 Ada 包装器中公开 DTLS 并更新示例（PR 7397）
• 新增额外的最小 TLS 扩展大小健全性检查（PR 7602）
• ESP 改进：更新示例和库，更新 Apple HomeKit SHA/SRP，并修复 SHA512 软件回退的字节序问题（PR 7607、7392、7505、7535）
• 通过定义宏 WOLFSSL_SMALL_CERT_VERIFY，使 wc_CheckCertSigPubKey API 公开可用（PR 7599）
• 新增 FIPS 140-3 完整提交的 alpha/预览版，将更多算法（如 SRTP-KDF、AES-XTS、GCM 流、AES-CFB、ED25519 和 ED448）纳入 FIPS 模块边界（PR 7295）
• 对 FIPS 模块 v5.2.3 的 XCODE 支持（PR 7140）
• 扩展 OpenSSL 兼容层并新增 EC_POINT_hex2point（PR 7191）

修复内容

• 修复了 NXP MMCAU 硬件加速的 SHA-256（PR 7389）
• 修复了 AES-CFB1 在（8*x-1）比特大小下的加密/解密问题（PR 7431）
• 修复了 SHA-256 x64 汇编中 %rip 的使用（PR 7409）
• 修复了 DTLS 的 OCSP 响应消息构建（PR 7671）
• 处理了 wc_ecc_mulmod() 中零值的边界情况（PR 7532）
• 修复了 RPK（原始公钥）以正确遵循证书使用方式（PR 7375）
• 为 QUIC 使用添加了记录头的完整性检查（PR 7638）
• 在解析时为 X.509 中的空目录字符串添加了完整性检查（PR 7669）
• 为解析的证书中不符合规范的序列号 0 添加了完整性检查（PR 7625）
• 修复了 wolfSSL_CTX_set1_sigalgs_list()，使 TLS 连接符合所选的签名哈希算法（PR 7693）
• 针对双算法证书的各种修复，包括减少堆栈使用和支持证书签名请求（PR 7577）
• 当 wolfSSL 构建时未启用策略扩展支持，为关键策略扩展添加了完整性检查（PR 7388）
• 添加了 ed25519 签名小于阶数的完整性检查（PR 7513）
• 修复了 Segger emNet 以处理非阻塞的需读/需写情况（PR 7581）

有关其他漏洞信息，请访问漏洞页面： https://www.wolfssl.com/docs/security-vulnerabilities/

构建说明参见 INSTALL 文件。 更多信息可在线查看：https://wolfssl.com/wolfSSL/Docs.html

资源

wolfSSL 官网

wolfSSL 维基

FIPS 140-2/140-3 常见问题

wolfSSL 文档

wolfSSL 手册

wolfSSL API 参考

wolfCrypt API 参考

TLS 1.3

wolfSSL 漏洞

更多 wolfSSL 示例

目录结构

<wolfssl_root>
├── 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]