沃尔夫斯勒

WolfSSL 嵌入式 SSL/TLS 库

WolfSSL 嵌入式 SSL 库（以前称为 CyaSSL）是一个用 ANSI C 编写的轻量级 SSL/TLS 库，面向嵌入式、RTOS 和资源受限环境 - 主要是因为它体积小、速度快且功能集少。由于其免版税定价和出色的跨平台支持，它也常用于标准操作环境。 WolfSSL 支持高达当前 TLS 1.3 和 DTLS 1.3 的行业标准，比 OpenSSL 小 20 倍，并提供渐进式密码，例如 ChaCha20、Curve25519、Blake2b 和 Post-Quantum TLS 1.3 组。用户基准测试和反馈报告显示，使用 WolfSSL 比 OpenSSL 时的性能显着提高。

WolfSSL 由 WolfCrypt 加密库提供支持。 WolfCrypt 的两个版本已通过 FIPS 140-2 验证（证书#2425 和证书#3389）。 FIPS 140-3 验证正在进行中。如需更多信息，请访问 WolfCrypt FIPS 常见问题解答或联系 [email protected]。

为什么选择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

当使用--enable-opensslextra ( OPENSSL_EXTRA ) 或宏NO_OLD_SHA_NAMES构建 WolfSSL 时，枚举值 SHA、SHA256、SHA384、SHA512 不再可用。这些名称被映射到 OpenSSL API 以用于单个调用哈希函数。相反，应使用名称WC_SHA 、 WC_SHA256 、 WC_SHA384和WC_SHA512作为枚举名称。

WolfSSL 版本 5.7.4（2024 年 10 月 24 日）

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

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

PR 代表 Pull Request，PR 引用添加代码更改的 GitHub 拉取请求编号。

漏洞

• [低] 启用 OpenSSL 兼容层时，在 X509_STORE_add_cert() 和 X509_STORE_load_locations() 实现中，wolfSSL 中的证书验证行为与 OpenSSL 不同。以前，在应用程序显式加载中间证书的情况下，wolfSSL 仅验证该中间证书，而不是验证根 CA。这仅影响直接调用 API 的用例，不会影响 TLS 连接。建议直接在应用程序中调用 API X509_STORE_add_cert() 或 X509_STORE_load_locations() 的用户更新所使用的 WolfSSL 版本，或者在验证证书时对加载到 X509_STORE 中的证书进行额外的健全性检查。 (#8087)

PQC TLS 实验性构建修复

• 当使用启用后量子算法的 TLS 时，连接使用的 EC 曲线比商定的要小。建议使用 --enable-experimental 构建并启用具有 TLS 连接的 PQC 密码套件的用户更新所使用的 WolfSSL 版本。感谢丹尼尔·科雷亚的报告。 (#8084)

添加新功能

• 为 SHA-256、SHA-512、ChaCha20、Poly1305 和 SHA-3 添加了 RISC-V 64 新的汇编优化（PR 7758,7833,7818,7873,7916）
• 使用 DTLS 1.2 实现对连接 ID (CID) 的支持 (PR 7995)
• 添加对 (DevkitPro)libnds 的支持 (PR 7990)
• 添加 Mosquitto OSP（开源项目）端口 (PR 6460)
• 为 init sssd 添加端口 (PR 7781)
• 添加 eXosip2 端口 (PR 7648)
• 添加对 STM32G4 的支持 (PR 7997)
• 添加对 MAX32665 和 MAX32666 TPU HW 以及 ARM ASM 加密回调支持的支持 (PR 7777)
• 添加对构建用于 libspdm 的 WolfSSL 的支持 (PR 7869)
• 添加端口以与 Nucleus Plus 2.3 (PR 7732) 一起使用
• 最初支持 RFC5755 x509 属性证书 (acerts)。使用 --enable-acert 启用（PR 7926）
• PKCS#11 RSA Padding 卸载允许令牌执行 CKM_RSA_PKCS（签名/加密）、CKM_RSA_PKCS_PSS（签名）和 CKM_RSA_PKCS_OAEP（加密）。 （公关7750）
• 添加了“新”和“删除”样式函数，用于堆/池分配和释放低级加密结构（PR 3166 和 8089）

增强和优化

• 增加默认最大替代值。名称从 128 到 1024 (PR 7762)
• 添加了新的恒定时间 DH 同意函数 wc_DhAgree_ct (PR 7802)
• 扩展了 API EVP_PKEY_is_a 的兼容性层 (PR 7804)
• 添加选项以使用 --disable-cryptocb-sw-test 禁用 cryptocb 测试软件测试 (PR 7862)
• 在检查证书日期之前添加对证书验证回调的调用 (PR 7895)
• WolfCrypt CSharp 包装器支持扩展算法。添加对 RNG、ECC（ECIES 和 ECDHE）、RSA、ED25519/Curve25519、AES-GCM 和哈希的支持 (PR 3166)
• 扩展 MMCAU 支持以与 DES ECB 一起使用 (PR 7960)
• 更新 AES SIV 以处理多个关联的数据输入 (PR 7911)
• 从 --enable-openssh 中删除 HAVE_NULL_CIPHER (PR 7811)
• 调用 XFREE 时删除了重复的 if(NULL) 检查（宏执行）（PR 7839）
• 将 RSA_MIN_SIZE 默认设置为 2048 位 (PR 7923)
• 添加了对 WolfSSL 的支持，以用作 zephyr 内核中的默认 TLS（PR 7731）
• 使用 --enable-wolfprovider 和 autotools 添加启用提供程序构建 (PR 7550)
• 瑞萨电子 RX TSIP ECDSA 支持 (PR 7685)
• 服务器支持CID时支持DTLS1.3降级（PR 7841）
• 服务器端检查 OCSP，即使它使用 v2 multi (PR 7828)
• 在 PKCS7 包解析和创建中添加对缺少的哈希参数的处理 (PR 7845)
• 为 Poly1305 添加 w64wrapper 的使用，使 Poly1305 能够在没有 word64 类型的环境中使用 (PR 7759)
• 更新 maxq10xx 支持 (PR 7824)
• 添加对解析可选 PKCS8 属性的支持 (PR 7944)
• 使用 DTLS 1.3 添加对任一方方法的支持 (PR 8012)
• 添加了 PKCS7 PEM 支持，用于使用 BEGIN/END PKCS7 解析 PEM 数据（PR 7704）
• 添加对 WOLFSSL_CUSTOM_CURVES 的 CMake 支持 (PR 7962)
• 向 X509_check_host() 添加最左侧通配符匹配支持 (PR 7966)
• 添加选项以通过 PKCS7 捆绑包创建设置自定义 SKID (PR 7954)
• 使用 Ada 构建 WolfSSL 作为库并更正 Alire 清单 (PR 7303,7940)
• 瑞萨电子 RX72N 支持更新 (PR 7849)
• 添加了新选项 WOLFSSL_COPY_KEY 以始终将密钥复制到 SSL 对象 (PR 8005)
• 添加新选项 WOLFSSL_COPY_CERT 以始终复制每个 SSL 对象的证书缓冲区 (PR 7867)
• 添加一个选项以将 AES-CBC 与 HMAC 结合使用作为默认会话票证 enc/dec。默认为 AES-128-CBC 和 HMAC-SHA256 (PR 7703)
• wc_PRF、sha256（适用于许多寄存器可用时的小代码）和 sp_int 对象中的内存使用改进 (PR 7901)
• 更改配置脚本以在不使用命令的情况下解决“>>”问题。在较旧的 /bin/sh 中，它可能不明确，如 FreeBSD 9.2 (PR 7876) 等操作系统中使用的那样
• 不需要时不要尝试包含系统标头 (PR 7813)
• 证书：ECC 签名算法参数的 DER 编码现在允许通过定义为 NULL (PR 7903)
• SP x86_64 asm：检查虚拟机的 AVX2 支持 (PR 7979)
• 更新 gr-rose 上的 rx64n 支持 (PR 7889)
• 将 RA6M4 的 FSP 版本更新至 v5.4.0 (PR 7994)
• 将 RX65N RSK 的 TSIP 驱动程序版本更新至 v1.21 (PR 7993)
• 为带有填充的 RSA 添加新的加密回调（PR 7907）
• 将 pqm4 的使用替换为 Kyber/MLDSA 的 WolfSSL 实现（PR 7924）
• 对 C11 和 clang 的现代化内存栅栏支持 (PR 7938)
• 添加 CRL 错误覆盖回调 (PR 7986)
• 扩展 X509 未知扩展回调以与用户上下文一起使用 (PR 7730)
• 使用 TLS 添加了额外的调试错误跟踪 (PR 7917)
• 使用 libbacktrace 添加了对库调用堆栈跟踪的运行时支持 –enable-debug-trace-errcodes=backtrace (PR 7846)
• 扩展的 C89 合规性 (PR 8077)
• 扩展了对 WOLFSSL_NO_MALLOC 的支持（PR 8065）
• 添加了对 Linux 内核模块交叉编译的支持 (PR 7746)
• 更新了 Linux 内核模块，支持内核 6.11 和 6.12 (PR 7826)
• 引入 WOLFSSL_ASN_ALLOW_0_SERIAL 以允许解析序列号为 0 的证书 (PR 7893)
• 将条件repository_owner添加到所有wolfSSL GitHub工作流程（PR 7871）

乐鑫 / Arduino 更新

• 更新 Espressif ESP-IDF 的 Wolfcrypt settings.h，模板更新（PR 7953）
• 更新 Espressif sha、util、mem、时间助手 (PR 7955)
• Espressif _thread_local_start 和 _thread_local_end 修复（PR 8030）
• 改进乐鑫设备的基准测试 (PR 8037)
• 引入 Espressif 常用 CONFIG_WOLFSSL_EXAMPLE_NAME、Kconfig (PR 7866)
• 添加对 Espressif ESP-IDF 的 WolfSSL esp-tls 和证书捆绑支持 (PR 7936)
• 更新 Arduino 的 Wolfssl 版本 (PR 7775)

后量子加密更新

• Dilithium：支持 dilithium_key 中的固定大小数组（PR 7727）
• Dilithium：添加使用带有小符号的预计算选项（PR 7744）
• 允许使用 FIPS 构建 Kyber (PR 7788)
• 允许在 Linux 内核模块中使用 Kyber asm (PR 7872)
• Dilithium、Kyber：更新至最终规范 (PR 7877)
• Dilithium：支持 FIPS 204 草案和最终草案 (PR 7909,8016)

ARM 汇编优化

• 为 ChaCha20 和 Poly1305 添加了 ARM32 汇编优化 (PR 8020)
• 针对 Aarch64 的 Poly1305 装配优化改进 (PR 7859)
• 为 Thumb-2 添加了 Poly1305 装配优化 (PR 7939)
• 将 ARM ASM 构建选项添加到 STM32CubePack (PR 7747)
• 将 ARM64 添加到 Visual Studio 项目 (PR 8010)
• 针对 ARM32 和 Aarch64 的 Kyber 程序集优化（PR 8040,7998）
• 针对 ARMv7E-M/ARMv7-M 的 Kyber 程序集优化 (PR 7706)

修复

• ECC 密钥加载：修复了参数不是默认大小的证书 (PR 7751)
• 修复了在 Visual Studio 中为非 Windows 操作系统构建 x86 的问题 (PR 7884)
• 修复了 TLS v1.2 秘密回调，错误地检测到错误的主秘密 (PR 7812)
• 修复了 PowerPC 程序集与 Darwin 和 SP math all 一起使用的问题 (PR 7931)
• 修复了尝试链接 libdispatch 时检测旧版 Mac OS 的问题（PR 7932）
• 修复了当服务器发送多个握手数据包合并为一次传输时 DTLS1.3 降级到 DTLS1.2 的问题。 （公关7840）
• 修复了 OCSP 保存请求（如果请求存储在 ssl->ctx->certOcspRequest 中）的问题 (PR 7779)
• 修复了 OCSP 以通过密钥哈希而不是分机搜索 CA。密钥 ID（PR 7934）
• 修复静态内存和单线程构建 (PR 7737)
• 修复不允许 Shake128/256 与 Xilinx AFALG (PR 7708)
• 修复以支持 PKCS11，无需生成 RSA 密钥 (PR 7738)
• 修复使用 PK 回调 + TLS 1.3 时不调用签名回调的问题 (PR 7761)
• IAR 编译器的 Cortex-M/Thumb2 ASM 修复标签 (PR 7753)
• 修复 PKCS11 以正确迭代 slotId (PR 7736)
• 停止剥离 AltSigAlg 扩展上的序列标头 (PR 7710)
• 使用 ASN 模板修复 ParseCRL_AuthKeyIdExt 以设置 extAuthKeyIdSet 值 (PR 7742)
• 使用 PSK 加密缓冲区大小的最大密钥长度 (PR 7707)
• DTLS 1.3 修复了大小检查，包括标头和 CID 修复 (PR 7912,7951)
• 修复 STM32 哈希 FIFO 并添加对 STM32U5A9xx 的支持 (PR 7787)
• 修复curl 构建的 CMake 构建错误 (PR 8021)
• SP 数学：PowerPC ASM 修复为使用 XOR 而不是 LI (PR 8038)
• 密钥/证书的 SSL 加载：测试和修复 (PR 7789)
• 杂项。针对 Dilithium 和 Kyber 的修复（PR 7721,7765,7803,8027,7904）
• 修复了为 PQ LMS/XMSS 构建 WolfBoot 源的问题 (PR 7868)
• 修复了使用 CMake 和 zephyr 端口启用 Kyber 进行构建的问题 (PR 7773)
• 修复了使用 TLS 1.2 恢复会话的边缘情况 (PR 8097)
• 修复 ARM ASM 与 AES CFB/OFB 未初始化“左”成员的问题 (PR 8099)

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

有关构建说明，请参阅安装文件。更多信息可以在线找到：https://wolfssl.com/wolfSSL/Docs.html

资源

狼SSL网站

狼SSL 维基

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

狼SSL文档

狼SSL手册

WolfSSL API 参考

WolfCrypt API 参考

传输层安全协议1.3

WolfSSL 漏洞

其他 WolfSSL 示例

目录结构

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