ESP32 Arduino NetworkClientSecure 库实战TLS/SSL 安全连接的四种认证方式与完整 API 解析【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32本指南以 arduino-esp32 仓库中的 NetworkClientSecure 库 为蓝本系统讲解 ESP32 在 Arduino 环境下通过NetworkClientSecure建立 TLS/SSL 安全连接的四种认证方案根 CA 证书、根 CA 证书包、客户端证书/密钥、预共享密钥 PSK、ALPN 协议协商、STARTTLS 明文升级以及指纹校验等进阶用法。读完本文你将能够根据业务场景HTTPS 客户端、MQTT over TLS、mTLS 双向认证、SMTP STARTTLS 等正确选用并配置安全连接同时掌握其底层 mbedTLS 调用链与源码级实现细节。一、NetworkClientSecure 类概览安全连接的统一入口NetworkClientSecure位于 libraries/NetworkClientSecure/src/NetworkClientSecure.h它继承自NetworkClient因此实现了NetworkClient接口的完整超集所有 TCP 客户端的connect、write、read、available、peek、stop、connected等成员函数在安全连接上依然可用用法与非加密的NetworkClient几乎一致区别仅在于握手阶段完成 TLS 加密协商以及需要预先配置认证凭据。从源码结构看NetworkClientSecure.h类的核心成员包括std::shared_ptrsslclient_context sslclient保存底层 mbedTLS 上下文socket、SSL 配置、证书、密钥等的共享指针见 ssl_client.h_CA_cert/_cert/_private_keyPEM 格式的根 CA 证书、客户端证书、客户端私钥字符串_pskIdent/_psKeyPSK 模式的客户端标识与十六进制密钥_alpn_protosALPN 协议列表_use_ca_bundle/_use_insecure是否使用证书包、是否跳过验证。该库提供WiFiClientSecure.h头文件作为别名封装同目录下的 WiFiClientSecure.h两者等价可按习惯引用。二、方式一使用根 CA 证书验证服务器标准 HTTPS 模式这是最常用、也是最接近浏览器 HTTPS 行为的方式客户端使用根 CA 证书验证服务器出示的证书链并协商加密连接。凭据准备访问自有服务器需要先用工具如 openssl生成属于你自己的 CA 根证书再使用该根证书为服务器签发一张自签名证书与私钥访问公共服务器获取签署该服务器证书的公共 CA 根证书通常可从 CA 官网或证书链信息中获得。编程步骤在 NetworkClientSecure.cpp 中setCACert()将根证书字符串存入_CA_cert并清除_use_insecure标志随后调用connect(host, port)时connect() 会把_CA_cert传入底层握手函数。仓库示例 WiFiClientSecure.ino 展示了完整流程#include Arduino.h #include NetworkClientSecure.h #include WiFi.h const char *ssid your-ssid; const char *password your-password; const char *server www.howsmyssl.com; // 目标服务器 // 用于验证服务器的根 CA 证书PEM 格式换成你自己的服务器根 CA const char *test_root_ca Rliteral( -----BEGIN CERTIFICATE----- MIIFBTCCAu2gAwIBAgIQS6hSk/eaL6JzBkuoBI110DANBgkqhkiG9w0BAQsFADBP ...此处省略证书正文 -----END CERTIFICATE----- )literal; NetworkClientSecure client; void setup() { Serial.begin(115200); delay(100); WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(1000); } client.setCACert(test_root_ca); // 设置根 CA 证书 if (!client.connect(server, 443)) { Serial.println(Connection failed!); } else { client.println(GET https://www.howsmyssl.com/a/check HTTP/1.0); client.println(Host: www.howsmyssl.com); client.println(Connection: close); client.println(); while (client.connected()) { String line client.readStringUntil(\n); if (line \r) break; // 读完响应头 } while (client.available()) { Serial.write(client.read()); } client.stop(); } } void loop() {}底层验证逻辑在 ssl_client.cpp 中当传入rootCABuff时通过mbedtls_ssl_conf_authmode()设置MBEDTLS_SSL_VERIFY_REQUIRED强制验证服务器证书通过mbedtls_x509_crt_parse()解析 PEM 根证书通过mbedtls_ssl_conf_ca_chain()将根证书挂载到 SSL 配置的信任链上。注意示例代码中的注释提醒SHA1 fingerprint is broken now!即不要依赖 SHA1 指纹做安全校验务必使用 CA 证书或下文介绍的 SHA256 指纹方案。另外示例注释也说明可通过setCertificate/setPrivateKey附带客户端证书实现双向认证见第四节。三、方式二使用根 CA 证书包Built-in CA Bundle当需要连接任意公共 SSL 服务器、又不想为每台服务器硬编码单个根证书时可以使用来自 Mozilla 的标准根证书包。与方式一只接受给定服务器的一个证书不同证书包模式内置了一整套公共根证书客户端可以连接所有受信任的公共 SSL 服务器。启用方式使用useBuiltinCACertBundle()直接启用编译进固件的内置证书包需要目标芯片支持esp_crt_bundle特性使用setCACertBundle(bundle, size)传入自定义的证书包数据PEM/DER 格式源码见 NetworkClientSecure.cpp。仓库示例 WiFiClientSecureBuiltinCACertBundle.ino 的核心调用只有一行client.useBuiltinCACertBundle(); // client.setCACert(test_root_ca); // 与证书包二选一对应实现NetworkClientSecure.cpp调用attach_ssl_certificate_bundle(sslclient.get(), true)该函数ssl_client.cpp将回调esp_crt_bundle_attach存入sslclient_context::bundle_attach_cb握手时ssl_client.cpp通过该回调把证书包附加到 SSL 配置上。使用注意README 特别指出在 Arduino IDE 下的两种替代方案编写 Makefile在其中加入idf_component_register()声明以包含证书包将证书包存放为 SPIFFS 文件但运行时需要加载进 RAM会浪费约 64k 宝贵的内部内存——除非确有需要优先推荐内置证书包方式。三种验证方式优先级源码佐证在 start_ssl_client() 中若rootCABuff、PSK、insecure、useRootCABundle均为空/假函数直接返回 -1拒绝无凭据连接。实际验证逻辑按以下顺序分支优先级条件采用的 mbedTLS 配置1insecure trueMBEDTLS_SSL_VERIFY_NONE不校验见 ssl_client.cpp2rootCABuff ! NULLMBEDTLS_SSL_VERIFY_REQUIRED 单根 CA3useRootCABundle true附加 Mozilla 证书包回调4pskIdent ! NULL psKey ! NULLmbedtls_ssl_conf_psk()PSK 套件四、方式三根 CA 客户端证书/私钥双向 TLS / mTLS某些场景如物联网设备接入私有平台、银行/企业网关要求服务器验证客户端身份即双向认证。此时客户端需要三样东西根 CA用于验证服务器、客户端证书、客户端私钥用于向服务器自证身份。配置步骤按方式一准备好根 CA 证书或使用公共 CA使用该根 CA 为你的客户端签发证书与私钥把客户端的证书/公钥注册到目标服务器上使服务器能够认证你的客户端在代码中同时调用setCACert()、setCertificate()、setPrivateKey()或使用带证书参数的connect()重载。源码层面NetworkClientSecure.cppsetCertificate/setPrivateKey分别保存客户端证书与私钥字符串在 ssl_client.cpp 中只要cli_cert与cli_key同时非空且非 insecure 模式就通过mbedtls_x509_crt_parse()解析客户端证书、通过mbedtls_pk_parse_key()解析私钥。注意源码注释强调证书与私钥必须成对提供Note - this check for BOTH key and cert is relied on later during cleanup只给其一会导致解析或清理异常。对应connect()重载签名NetworkClientSecure.hint connect(const char *host, uint16_t port, const char *rootCABuff, const char *cli_cert, const char *cli_key); int connect(IPAddress ip, uint16_t port, const char *rootCABuff, const char *cli_cert, const char *cli_key);示例 WiFiClientSecure.ino 中已预留注释代码取消注释即可启用client.setCACert(test_root_ca); //client.setCertificate(test_client_cert); // 客户端证书用于服务器端验证 //client.setPrivateKey(test_client_key); // 客户端私钥五、方式四预共享密钥 PSK轻量级 MQTT 认证PSKPre-Shared Key是 TLS 支持的另一种认证与加密方式客户端与服务器预先共享一个密钥替代 HTTPS 常用的公钥密码体系。README 指出PSK 正越来越多地用于 MQTT例如 mosquitto以简化部署、省去完整的 CA/证书/私钥签发流程。PSK 原理要点PSK 是最长 32 字节的二进制串通常以十六进制形式表示客户端除密钥外还可提供一个id标识服务器通常允许为每个客户端 id 关联不同的密钥——这非常类似于用户名 密码对与密码不同密钥不会被直接传输给服务器因此即使连接到恶意服务器也不会泄露密钥同时服务器也会向客户端证明它拥有该密钥即双向认证。配置步骤生成一个随机十六进制串例如对某个文件计算 MD5 或 SHA 摘要就是一种可行方法为客户端设计一个字符串 id并在服务器端配置接受该 id/key 对代码中调用setPreSharedKey(pskIdent, psKey)或带 PSK 参数的connect()连接时客户端使用 id/key 组合认证服务器服务器必须证明自己持有密钥、认证客户端然后协商加密连接。完整示例MQTT 场景仓库示例 WiFiClientPSK.ino 展示了对 8443 端口MQTT 通常用 8883发起 PSK 安全连接#include Arduino.h #include NetworkClientSecure.h #include WiFi.h const char *ssid test; const char *password securetest; const IPAddress server IPAddress(192, 168, 0, 14); // 服务器 IP const int port 8443; // 8443 或 MQTT 的 8883 const char *pskIdent Client_identity; // PSK 标识有时称为 key hint const char *psKey 1a2b3c4d; // PSK 密钥必须是不带 0x 前缀的十六进制串 NetworkClientSecure client; void setup() { Serial.begin(115200); WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(1000); } client.setPreSharedKey(pskIdent, psKey); if (!client.connect(server, port)) { Serial.println(Connection failed!); } else { client.println(GET /a/check HTTP/1.0); client.print(Host: ); client.println(server); client.println(Connection: close); client.println(); // ... 读取响应 client.stop(); } } void loop() {}示例文件头部还给出了本地联调命令用 openssl 起一个无证书的 PSK 测试服务器openssl s_server -accept 8443 -psk 1a2b3c4d -nocertPSK 的底层处理在 ssl_client.cpp 中PSK 密钥需满足十六进制串长度必须为偶数strlen(psKey) 1为 0长度不得超过2 * MBEDTLS_PSK_MAX_LEN对应 32 字节的二进制密钥逐字符解析 0-9、A-F、a-f非法字符直接返回 -1最终调用mbedtls_ssl_conf_psk()配置到 SSL 上下文。需要特别留意文件顶部的编译期检查ssl_client.cpp会输出警告——若固件未启用 PSK 密码套件需要通过idf.py menuconfig在Component config - mbedTLS - TLS Key Exchange Methods中勾选 Enable PSK based ciphersuite modes否则应使用 CMake/Arduino 构建系统对应的 Kconfig 配置开启。六、不安全模式与 TOFU 折中方案setInsecure()完全跳过验证慎用client.setInsecure(); // 不验证证书链接受服务器出示的任何证书——极不安全实现见 NetworkClientSecure.cpp清空所有证书与 PSK 凭据并置_use_insecure true底层对应MBEDTLS_SSL_VERIFY_NONE。示例 WiFiClientInsecure.ino 顶部注释明确警示这是totally insecure的做法仅当正规方案无法工作时才作为最后手段且优先考虑 TOFU 方案。生产环境不要使用。TOFUTrust On First Use首次使用信任示例 WiFiClientTrustOnFirstUse.ino 实现了介于完全信任与硬编码 CA之间的折中方案首次连接在可信网络环境下以 insecure 模式进行获取服务器证书的 SHA256 指纹并存入 EEPROM示例使用EEPROMClass TOFU(tofu0)分配独立命名空间后续连接同样以 insecure 模式建链因为不使用 CA 校验但建链后通过getFingerprintSHA256()获取当前对端指纹与 EEPROM 中保存的指纹比对不一致则中断连接提供信任重置机制示例将 GPIO 35TOFU_RESET_BUTTON接到按键启动时若该引脚为低电平则重新执行 TOFU 并重启设备。该方案适合服务器证书生命周期长于 IoT 设备固件更新周期、不便长期硬编码根证书的场景。其思路与 WiFiClientShowPeerCredentials 中的指纹提取 API 相互配合。七、对端证书查看与指纹校验在 IoT 场景中你可能需要确认确实连接到了正确的服务器。NetworkClientSecure提供了两个关键 APINetworkClientSecure.hgetPeerCertificate()返回const mbedtls_x509_crt *可配合mbedtls_x509_crt_info()打印证书详情getFingerprintSHA256(uint8_t sha256_result[32])获取对端证书的 SHA256 指纹底层由 get_peer_fingerprint() 实现verify(const char *fingerprint, const char *domain_name)连接后校验指纹与域名是否匹配NetworkClientSecure.cpp。示例 WiFiClientShowPeerCredentials.ino 演示了完整用法#include HTTPClient.h #include NetworkClientSecure.h NetworkClientSecure *client new NetworkClientSecure; client-setInsecure(); // 演示需要生产环境建议配合 CA 或 TOFU HTTPClient https; https.begin(*client, https://arduino.cc); int httpCode https.GET(); // 建链并请求 const mbedtls_x509_crt *peer client-getPeerCertificate(); char buf[1024]; mbedtls_x509_crt_info(buf, sizeof(buf), , peer); // 打印证书信息 Serial.println(buf); uint8_t fingerprint_remote[32]; if (client-getFingerprintSHA256(fingerprint_remote)) { // 与期望值比对 for (int i 0; i 32; i) { Serial.print(fingerprint_remote[i], HEX); Serial.print( ); } }该例特别指出指纹方案的适用价值根证书往往比 IoT 硬件生命周期更换得更频繁指纹校验适合无法长期硬编码可信根证书的场景。八、ALPN 协议协商ALPNApplication-Layer Protocol Negotiation是 TLS 扩展允许应用层在安全连接上协商使用哪种上层协议避免额外的往返开销且与具体应用层协议无关。典型场景是AWS IoT Custom AuthorizersMQTT 客户端必须将 ALPN 协议设置为mqtt。const char *aws_protos[] {mqtt, NULL}; // ... wiFiClient.setAlpnProtocols(aws_protos);API 见 NetworkClientSecure.h实现在 NetworkClientSecure.cpp 中仅保存指针握手阶段ssl_client.cpp通过mbedtls_ssl_conf_alpn_protocols()配置到 SSL 上下文。协议列表以NULL结尾的const char *数组传入。九、STARTTLS明文连接升级到加密连接某些协议SMTP、XMPP、MySQL、PostgreSQL 等允许或要求先以明文建链再通过命令切换到加密。NetworkClientSecure为此提供PlainStart模式setPlainStart()让客户端以普通 TCP 明文方式启动默认关闭见 NetworkClientSecure.hstartTLS()在恰当的时机触发 TLS 握手升级返回 0 表示失败非 0 表示成功NetworkClientSecure.h。底层在明文阶段write/read/available会走send_net_data/get_net_receive等普通网络路径NetworkClientSecure.cpp调用startTLS()后NetworkClientSecure.cpp执行ssl_starttls_handshake()并清除_stillinPlainStart标志此后读写切换为 mbedTLS 加密通道。示例 WiFiClientSecureProtocolUpgrade.ino 以 SMTP587 端口展示了完整对话流程1. 客户端明文连接服务器 2. 服务器发送问候 3. 客户端发送 EHLO 4. 服务器告知支持 SSL/TLS 5. 客户端发送 STARTTLS 6. 客户端/服务器协商 SSL/TLS 连接 7. 客户端再次发送 EHLO此时已加密 8. 服务器告知加密后支持的能力如更多认证选项核心代码client.setInsecure(); // 演示用生产环境至少应启用 TOFU 或硬编码 CA client.setPlainStart(); // 先以明文启动 if (!client.connect(server, SMTP_PORT)) { /* 失败处理 */ } client.print(EHLO there\r\n); // 明文 client.print(STARTTLS\r\n); // 明文发送升级指令 if (client.startTLS() 0) { // 升级到 TLS /* 升级失败处理 */ } client.print(EHLO again\r\n); // 加密通道 client.print(QUIT\r\n);十、连接、读写与超时控制connect() 重载家族NetworkClientSecure.h 声明了多组重载覆盖主机名/IP 端口 可选凭据 可选超时的组合connect(host, port)/connect(ip, port)使用之前 setter 配置的凭据连接connect(host, port, timeout)/connect(ip, port, timeout)额外指定超时毫秒connect(host, port, rootCABuff, cli_cert, cli_key)临时指定三件套connect(host, port, pskIdent, psKey)临时指定 PSK。从 NetworkClientSecure.cpp 可见connect(ip, port)会优先检查是否已设置 PSK_pskIdent _psKey否则回退到 CA 证书路径带超时的重载会更新_timeout后转调无超时版本。默认超时与自定义构造时_timeout 30000毫秒sslclient-handshake_timeout 120000毫秒见 NetworkClientSecure.cpp底层 TCP 连接超时同样默认 30000msssl_client.cpp超时或失败时关闭 socket 并返回失败握手超时可通过setHandshakeTimeout(unsigned long seconds)设置NetworkClientSecure.cpp。连接建立后底层还会配置SO_RCVTIMEO/SO_SNDTIMEO即_timeout、TCP_NODELAY、SO_KEEPALIVE等 socket 选项ssl_client.cpp。错误信息握手或读写失败时可通过lastError(char *buf, size_t size)获取 mbedTLS 错误码及其可读文本内部调用mbedtls_strerror见 NetworkClientSecure.cpp便于排查证书解析、PSK 配置等问题。十一、从流中加载证书对于体积较大的证书也可以从任意Stream如 SPIFFS/LittleFS 文件、SD 卡读取bool loadCACert(Stream stream, size_t size); bool loadCertificate(Stream stream, size_t size); bool loadPrivateKey(Stream stream, size_t size);实现见 NetworkClientSecure.cpp_streamLoad()动态分配size 1字节缓冲区并读满随后转调对应的 setter并置_ca_cert_free/_cert_free/_private_key_free标志以便析构时释放内存。十二、示例清单速览NetworkClientSecure库在 libraries/NetworkClientSecure/examples 下提供 8 个官方示例覆盖上述全部主题示例目录主题关键 APIWiFiClientSecureCA 证书验证TLS 1.2 mbedTLSsetCACertWiFiClientPSKPSK 预共享密钥适合 mosquitto 等 MQTT 服务器setPreSharedKeyWiFiClientInsecure跳过验证极不安全慎用setInsecureWiFiClientSecureBuiltinCACertBundle内置 Mozilla 根证书包useBuiltinCACertBundleWiFiClientShowPeerCredentials显示对端证书与 SHA256 指纹getPeerCertificate/getFingerprintSHA256WiFiClientTrustOnFirstUseTOFU 首次信任 EEPROM 持久化指纹setInsecuregetFingerprintSHA256WiFiClientSecureProtocolUpgradeSTARTTLS 明文升级SMTP 场景setPlainStart/startTLSWiFiClientSecureEnterpriseWPA/WPA2 Enterprise如 eduroam HTTPS匿名身份/用户名/密码其中WiFiClientSecureEnterprise示例在 README 中被标记为outdated可能无法工作如需 WPA2-Enterprise 相关实现可参考社区维护的 ESP32-eduroam 项目另外三个示例Secure/PSK/Insecure均运行于 TLS 1.2 mbedTLS并在 WiFiClientSecure.ino 注释中列出了完整的受支持密码套件清单含 ECDHE/DHE/PSK/RSA 各类 AES-GCM/CCM/CBC 组合。十三、常见问题与排查要点PSK 连接失败先确认固件已开启 PSK 密码套件menuconfig/Kconfig 中启用 Enable PSK based ciphersuite modes并检查密钥是否为偶数长度、不超过 64 个十六进制字符、不含0x前缀ssl_client.cpp 会直接返回 -1。未配置任何凭据就 connectstart_ssl_client()会直接返回 -1日志提示rootCABuff NULL pskIdent NULL psKey NULL !insecure !useRootCABundle。证书解析失败确认 PEM 字符串以-----BEGIN CERTIFICATE-----开头并完整结束解析失败时底层会释放对应证书结构防止堆内存泄漏见 ssl_client.cpp 的注释。connect返回 0 但原因不明使用lastError()读取 mbedTLS 错误码底层日志log_e会附带错误号与可读描述ssl_client.cpp。证书有效期问题根证书会随 CA 更新而轮换若固件生命周期较长可考虑 TOFU 或证书包方案而非硬编码单一根证书。综上NetworkClientSecure在单一类接口下完整覆盖了 HTTPS 客户端、mTLS 双向认证、PSK MQTT、STARTTLS 协议升级与证书指纹校验等主流安全连接场景结合 ssl_client.cpp 底层的 mbedTLS 调用链开发者可以在掌握实操 API 的同时理解每次握手的验证逻辑与内存管理细节从而为 ESP32 项目选择最合适的安全策略。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ESP32 Arduino NetworkClientSecure 库实战：TLS/SSL 安全连接的四种认证方式与完整 API 解析
ESP32 Arduino NetworkClientSecure 库实战TLS/SSL 安全连接的四种认证方式与完整 API 解析【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32本指南以 arduino-esp32 仓库中的 NetworkClientSecure 库 为蓝本系统讲解 ESP32 在 Arduino 环境下通过NetworkClientSecure建立 TLS/SSL 安全连接的四种认证方案根 CA 证书、根 CA 证书包、客户端证书/密钥、预共享密钥 PSK、ALPN 协议协商、STARTTLS 明文升级以及指纹校验等进阶用法。读完本文你将能够根据业务场景HTTPS 客户端、MQTT over TLS、mTLS 双向认证、SMTP STARTTLS 等正确选用并配置安全连接同时掌握其底层 mbedTLS 调用链与源码级实现细节。一、NetworkClientSecure 类概览安全连接的统一入口NetworkClientSecure位于 libraries/NetworkClientSecure/src/NetworkClientSecure.h它继承自NetworkClient因此实现了NetworkClient接口的完整超集所有 TCP 客户端的connect、write、read、available、peek、stop、connected等成员函数在安全连接上依然可用用法与非加密的NetworkClient几乎一致区别仅在于握手阶段完成 TLS 加密协商以及需要预先配置认证凭据。从源码结构看NetworkClientSecure.h类的核心成员包括std::shared_ptrsslclient_context sslclient保存底层 mbedTLS 上下文socket、SSL 配置、证书、密钥等的共享指针见 ssl_client.h_CA_cert/_cert/_private_keyPEM 格式的根 CA 证书、客户端证书、客户端私钥字符串_pskIdent/_psKeyPSK 模式的客户端标识与十六进制密钥_alpn_protosALPN 协议列表_use_ca_bundle/_use_insecure是否使用证书包、是否跳过验证。该库提供WiFiClientSecure.h头文件作为别名封装同目录下的 WiFiClientSecure.h两者等价可按习惯引用。二、方式一使用根 CA 证书验证服务器标准 HTTPS 模式这是最常用、也是最接近浏览器 HTTPS 行为的方式客户端使用根 CA 证书验证服务器出示的证书链并协商加密连接。凭据准备访问自有服务器需要先用工具如 openssl生成属于你自己的 CA 根证书再使用该根证书为服务器签发一张自签名证书与私钥访问公共服务器获取签署该服务器证书的公共 CA 根证书通常可从 CA 官网或证书链信息中获得。编程步骤在 NetworkClientSecure.cpp 中setCACert()将根证书字符串存入_CA_cert并清除_use_insecure标志随后调用connect(host, port)时connect() 会把_CA_cert传入底层握手函数。仓库示例 WiFiClientSecure.ino 展示了完整流程#include Arduino.h #include NetworkClientSecure.h #include WiFi.h const char *ssid your-ssid; const char *password your-password; const char *server www.howsmyssl.com; // 目标服务器 // 用于验证服务器的根 CA 证书PEM 格式换成你自己的服务器根 CA const char *test_root_ca Rliteral( -----BEGIN CERTIFICATE----- MIIFBTCCAu2gAwIBAgIQS6hSk/eaL6JzBkuoBI110DANBgkqhkiG9w0BAQsFADBP ...此处省略证书正文 -----END CERTIFICATE----- )literal; NetworkClientSecure client; void setup() { Serial.begin(115200); delay(100); WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(1000); } client.setCACert(test_root_ca); // 设置根 CA 证书 if (!client.connect(server, 443)) { Serial.println(Connection failed!); } else { client.println(GET https://www.howsmyssl.com/a/check HTTP/1.0); client.println(Host: www.howsmyssl.com); client.println(Connection: close); client.println(); while (client.connected()) { String line client.readStringUntil(\n); if (line \r) break; // 读完响应头 } while (client.available()) { Serial.write(client.read()); } client.stop(); } } void loop() {}底层验证逻辑在 ssl_client.cpp 中当传入rootCABuff时通过mbedtls_ssl_conf_authmode()设置MBEDTLS_SSL_VERIFY_REQUIRED强制验证服务器证书通过mbedtls_x509_crt_parse()解析 PEM 根证书通过mbedtls_ssl_conf_ca_chain()将根证书挂载到 SSL 配置的信任链上。注意示例代码中的注释提醒SHA1 fingerprint is broken now!即不要依赖 SHA1 指纹做安全校验务必使用 CA 证书或下文介绍的 SHA256 指纹方案。另外示例注释也说明可通过setCertificate/setPrivateKey附带客户端证书实现双向认证见第四节。三、方式二使用根 CA 证书包Built-in CA Bundle当需要连接任意公共 SSL 服务器、又不想为每台服务器硬编码单个根证书时可以使用来自 Mozilla 的标准根证书包。与方式一只接受给定服务器的一个证书不同证书包模式内置了一整套公共根证书客户端可以连接所有受信任的公共 SSL 服务器。启用方式使用useBuiltinCACertBundle()直接启用编译进固件的内置证书包需要目标芯片支持esp_crt_bundle特性使用setCACertBundle(bundle, size)传入自定义的证书包数据PEM/DER 格式源码见 NetworkClientSecure.cpp。仓库示例 WiFiClientSecureBuiltinCACertBundle.ino 的核心调用只有一行client.useBuiltinCACertBundle(); // client.setCACert(test_root_ca); // 与证书包二选一对应实现NetworkClientSecure.cpp调用attach_ssl_certificate_bundle(sslclient.get(), true)该函数ssl_client.cpp将回调esp_crt_bundle_attach存入sslclient_context::bundle_attach_cb握手时ssl_client.cpp通过该回调把证书包附加到 SSL 配置上。使用注意README 特别指出在 Arduino IDE 下的两种替代方案编写 Makefile在其中加入idf_component_register()声明以包含证书包将证书包存放为 SPIFFS 文件但运行时需要加载进 RAM会浪费约 64k 宝贵的内部内存——除非确有需要优先推荐内置证书包方式。三种验证方式优先级源码佐证在 start_ssl_client() 中若rootCABuff、PSK、insecure、useRootCABundle均为空/假函数直接返回 -1拒绝无凭据连接。实际验证逻辑按以下顺序分支优先级条件采用的 mbedTLS 配置1insecure trueMBEDTLS_SSL_VERIFY_NONE不校验见 ssl_client.cpp2rootCABuff ! NULLMBEDTLS_SSL_VERIFY_REQUIRED 单根 CA3useRootCABundle true附加 Mozilla 证书包回调4pskIdent ! NULL psKey ! NULLmbedtls_ssl_conf_psk()PSK 套件四、方式三根 CA 客户端证书/私钥双向 TLS / mTLS某些场景如物联网设备接入私有平台、银行/企业网关要求服务器验证客户端身份即双向认证。此时客户端需要三样东西根 CA用于验证服务器、客户端证书、客户端私钥用于向服务器自证身份。配置步骤按方式一准备好根 CA 证书或使用公共 CA使用该根 CA 为你的客户端签发证书与私钥把客户端的证书/公钥注册到目标服务器上使服务器能够认证你的客户端在代码中同时调用setCACert()、setCertificate()、setPrivateKey()或使用带证书参数的connect()重载。源码层面NetworkClientSecure.cppsetCertificate/setPrivateKey分别保存客户端证书与私钥字符串在 ssl_client.cpp 中只要cli_cert与cli_key同时非空且非 insecure 模式就通过mbedtls_x509_crt_parse()解析客户端证书、通过mbedtls_pk_parse_key()解析私钥。注意源码注释强调证书与私钥必须成对提供Note - this check for BOTH key and cert is relied on later during cleanup只给其一会导致解析或清理异常。对应connect()重载签名NetworkClientSecure.hint connect(const char *host, uint16_t port, const char *rootCABuff, const char *cli_cert, const char *cli_key); int connect(IPAddress ip, uint16_t port, const char *rootCABuff, const char *cli_cert, const char *cli_key);示例 WiFiClientSecure.ino 中已预留注释代码取消注释即可启用client.setCACert(test_root_ca); //client.setCertificate(test_client_cert); // 客户端证书用于服务器端验证 //client.setPrivateKey(test_client_key); // 客户端私钥五、方式四预共享密钥 PSK轻量级 MQTT 认证PSKPre-Shared Key是 TLS 支持的另一种认证与加密方式客户端与服务器预先共享一个密钥替代 HTTPS 常用的公钥密码体系。README 指出PSK 正越来越多地用于 MQTT例如 mosquitto以简化部署、省去完整的 CA/证书/私钥签发流程。PSK 原理要点PSK 是最长 32 字节的二进制串通常以十六进制形式表示客户端除密钥外还可提供一个id标识服务器通常允许为每个客户端 id 关联不同的密钥——这非常类似于用户名 密码对与密码不同密钥不会被直接传输给服务器因此即使连接到恶意服务器也不会泄露密钥同时服务器也会向客户端证明它拥有该密钥即双向认证。配置步骤生成一个随机十六进制串例如对某个文件计算 MD5 或 SHA 摘要就是一种可行方法为客户端设计一个字符串 id并在服务器端配置接受该 id/key 对代码中调用setPreSharedKey(pskIdent, psKey)或带 PSK 参数的connect()连接时客户端使用 id/key 组合认证服务器服务器必须证明自己持有密钥、认证客户端然后协商加密连接。完整示例MQTT 场景仓库示例 WiFiClientPSK.ino 展示了对 8443 端口MQTT 通常用 8883发起 PSK 安全连接#include Arduino.h #include NetworkClientSecure.h #include WiFi.h const char *ssid test; const char *password securetest; const IPAddress server IPAddress(192, 168, 0, 14); // 服务器 IP const int port 8443; // 8443 或 MQTT 的 8883 const char *pskIdent Client_identity; // PSK 标识有时称为 key hint const char *psKey 1a2b3c4d; // PSK 密钥必须是不带 0x 前缀的十六进制串 NetworkClientSecure client; void setup() { Serial.begin(115200); WiFi.begin(ssid, password); while (WiFi.status() ! WL_CONNECTED) { delay(1000); } client.setPreSharedKey(pskIdent, psKey); if (!client.connect(server, port)) { Serial.println(Connection failed!); } else { client.println(GET /a/check HTTP/1.0); client.print(Host: ); client.println(server); client.println(Connection: close); client.println(); // ... 读取响应 client.stop(); } } void loop() {}示例文件头部还给出了本地联调命令用 openssl 起一个无证书的 PSK 测试服务器openssl s_server -accept 8443 -psk 1a2b3c4d -nocertPSK 的底层处理在 ssl_client.cpp 中PSK 密钥需满足十六进制串长度必须为偶数strlen(psKey) 1为 0长度不得超过2 * MBEDTLS_PSK_MAX_LEN对应 32 字节的二进制密钥逐字符解析 0-9、A-F、a-f非法字符直接返回 -1最终调用mbedtls_ssl_conf_psk()配置到 SSL 上下文。需要特别留意文件顶部的编译期检查ssl_client.cpp会输出警告——若固件未启用 PSK 密码套件需要通过idf.py menuconfig在Component config - mbedTLS - TLS Key Exchange Methods中勾选 Enable PSK based ciphersuite modes否则应使用 CMake/Arduino 构建系统对应的 Kconfig 配置开启。六、不安全模式与 TOFU 折中方案setInsecure()完全跳过验证慎用client.setInsecure(); // 不验证证书链接受服务器出示的任何证书——极不安全实现见 NetworkClientSecure.cpp清空所有证书与 PSK 凭据并置_use_insecure true底层对应MBEDTLS_SSL_VERIFY_NONE。示例 WiFiClientInsecure.ino 顶部注释明确警示这是totally insecure的做法仅当正规方案无法工作时才作为最后手段且优先考虑 TOFU 方案。生产环境不要使用。TOFUTrust On First Use首次使用信任示例 WiFiClientTrustOnFirstUse.ino 实现了介于完全信任与硬编码 CA之间的折中方案首次连接在可信网络环境下以 insecure 模式进行获取服务器证书的 SHA256 指纹并存入 EEPROM示例使用EEPROMClass TOFU(tofu0)分配独立命名空间后续连接同样以 insecure 模式建链因为不使用 CA 校验但建链后通过getFingerprintSHA256()获取当前对端指纹与 EEPROM 中保存的指纹比对不一致则中断连接提供信任重置机制示例将 GPIO 35TOFU_RESET_BUTTON接到按键启动时若该引脚为低电平则重新执行 TOFU 并重启设备。该方案适合服务器证书生命周期长于 IoT 设备固件更新周期、不便长期硬编码根证书的场景。其思路与 WiFiClientShowPeerCredentials 中的指纹提取 API 相互配合。七、对端证书查看与指纹校验在 IoT 场景中你可能需要确认确实连接到了正确的服务器。NetworkClientSecure提供了两个关键 APINetworkClientSecure.hgetPeerCertificate()返回const mbedtls_x509_crt *可配合mbedtls_x509_crt_info()打印证书详情getFingerprintSHA256(uint8_t sha256_result[32])获取对端证书的 SHA256 指纹底层由 get_peer_fingerprint() 实现verify(const char *fingerprint, const char *domain_name)连接后校验指纹与域名是否匹配NetworkClientSecure.cpp。示例 WiFiClientShowPeerCredentials.ino 演示了完整用法#include HTTPClient.h #include NetworkClientSecure.h NetworkClientSecure *client new NetworkClientSecure; client-setInsecure(); // 演示需要生产环境建议配合 CA 或 TOFU HTTPClient https; https.begin(*client, https://arduino.cc); int httpCode https.GET(); // 建链并请求 const mbedtls_x509_crt *peer client-getPeerCertificate(); char buf[1024]; mbedtls_x509_crt_info(buf, sizeof(buf), , peer); // 打印证书信息 Serial.println(buf); uint8_t fingerprint_remote[32]; if (client-getFingerprintSHA256(fingerprint_remote)) { // 与期望值比对 for (int i 0; i 32; i) { Serial.print(fingerprint_remote[i], HEX); Serial.print( ); } }该例特别指出指纹方案的适用价值根证书往往比 IoT 硬件生命周期更换得更频繁指纹校验适合无法长期硬编码可信根证书的场景。八、ALPN 协议协商ALPNApplication-Layer Protocol Negotiation是 TLS 扩展允许应用层在安全连接上协商使用哪种上层协议避免额外的往返开销且与具体应用层协议无关。典型场景是AWS IoT Custom AuthorizersMQTT 客户端必须将 ALPN 协议设置为mqtt。const char *aws_protos[] {mqtt, NULL}; // ... wiFiClient.setAlpnProtocols(aws_protos);API 见 NetworkClientSecure.h实现在 NetworkClientSecure.cpp 中仅保存指针握手阶段ssl_client.cpp通过mbedtls_ssl_conf_alpn_protocols()配置到 SSL 上下文。协议列表以NULL结尾的const char *数组传入。九、STARTTLS明文连接升级到加密连接某些协议SMTP、XMPP、MySQL、PostgreSQL 等允许或要求先以明文建链再通过命令切换到加密。NetworkClientSecure为此提供PlainStart模式setPlainStart()让客户端以普通 TCP 明文方式启动默认关闭见 NetworkClientSecure.hstartTLS()在恰当的时机触发 TLS 握手升级返回 0 表示失败非 0 表示成功NetworkClientSecure.h。底层在明文阶段write/read/available会走send_net_data/get_net_receive等普通网络路径NetworkClientSecure.cpp调用startTLS()后NetworkClientSecure.cpp执行ssl_starttls_handshake()并清除_stillinPlainStart标志此后读写切换为 mbedTLS 加密通道。示例 WiFiClientSecureProtocolUpgrade.ino 以 SMTP587 端口展示了完整对话流程1. 客户端明文连接服务器 2. 服务器发送问候 3. 客户端发送 EHLO 4. 服务器告知支持 SSL/TLS 5. 客户端发送 STARTTLS 6. 客户端/服务器协商 SSL/TLS 连接 7. 客户端再次发送 EHLO此时已加密 8. 服务器告知加密后支持的能力如更多认证选项核心代码client.setInsecure(); // 演示用生产环境至少应启用 TOFU 或硬编码 CA client.setPlainStart(); // 先以明文启动 if (!client.connect(server, SMTP_PORT)) { /* 失败处理 */ } client.print(EHLO there\r\n); // 明文 client.print(STARTTLS\r\n); // 明文发送升级指令 if (client.startTLS() 0) { // 升级到 TLS /* 升级失败处理 */ } client.print(EHLO again\r\n); // 加密通道 client.print(QUIT\r\n);十、连接、读写与超时控制connect() 重载家族NetworkClientSecure.h 声明了多组重载覆盖主机名/IP 端口 可选凭据 可选超时的组合connect(host, port)/connect(ip, port)使用之前 setter 配置的凭据连接connect(host, port, timeout)/connect(ip, port, timeout)额外指定超时毫秒connect(host, port, rootCABuff, cli_cert, cli_key)临时指定三件套connect(host, port, pskIdent, psKey)临时指定 PSK。从 NetworkClientSecure.cpp 可见connect(ip, port)会优先检查是否已设置 PSK_pskIdent _psKey否则回退到 CA 证书路径带超时的重载会更新_timeout后转调无超时版本。默认超时与自定义构造时_timeout 30000毫秒sslclient-handshake_timeout 120000毫秒见 NetworkClientSecure.cpp底层 TCP 连接超时同样默认 30000msssl_client.cpp超时或失败时关闭 socket 并返回失败握手超时可通过setHandshakeTimeout(unsigned long seconds)设置NetworkClientSecure.cpp。连接建立后底层还会配置SO_RCVTIMEO/SO_SNDTIMEO即_timeout、TCP_NODELAY、SO_KEEPALIVE等 socket 选项ssl_client.cpp。错误信息握手或读写失败时可通过lastError(char *buf, size_t size)获取 mbedTLS 错误码及其可读文本内部调用mbedtls_strerror见 NetworkClientSecure.cpp便于排查证书解析、PSK 配置等问题。十一、从流中加载证书对于体积较大的证书也可以从任意Stream如 SPIFFS/LittleFS 文件、SD 卡读取bool loadCACert(Stream stream, size_t size); bool loadCertificate(Stream stream, size_t size); bool loadPrivateKey(Stream stream, size_t size);实现见 NetworkClientSecure.cpp_streamLoad()动态分配size 1字节缓冲区并读满随后转调对应的 setter并置_ca_cert_free/_cert_free/_private_key_free标志以便析构时释放内存。十二、示例清单速览NetworkClientSecure库在 libraries/NetworkClientSecure/examples 下提供 8 个官方示例覆盖上述全部主题示例目录主题关键 APIWiFiClientSecureCA 证书验证TLS 1.2 mbedTLSsetCACertWiFiClientPSKPSK 预共享密钥适合 mosquitto 等 MQTT 服务器setPreSharedKeyWiFiClientInsecure跳过验证极不安全慎用setInsecureWiFiClientSecureBuiltinCACertBundle内置 Mozilla 根证书包useBuiltinCACertBundleWiFiClientShowPeerCredentials显示对端证书与 SHA256 指纹getPeerCertificate/getFingerprintSHA256WiFiClientTrustOnFirstUseTOFU 首次信任 EEPROM 持久化指纹setInsecuregetFingerprintSHA256WiFiClientSecureProtocolUpgradeSTARTTLS 明文升级SMTP 场景setPlainStart/startTLSWiFiClientSecureEnterpriseWPA/WPA2 Enterprise如 eduroam HTTPS匿名身份/用户名/密码其中WiFiClientSecureEnterprise示例在 README 中被标记为outdated可能无法工作如需 WPA2-Enterprise 相关实现可参考社区维护的 ESP32-eduroam 项目另外三个示例Secure/PSK/Insecure均运行于 TLS 1.2 mbedTLS并在 WiFiClientSecure.ino 注释中列出了完整的受支持密码套件清单含 ECDHE/DHE/PSK/RSA 各类 AES-GCM/CCM/CBC 组合。十三、常见问题与排查要点PSK 连接失败先确认固件已开启 PSK 密码套件menuconfig/Kconfig 中启用 Enable PSK based ciphersuite modes并检查密钥是否为偶数长度、不超过 64 个十六进制字符、不含0x前缀ssl_client.cpp 会直接返回 -1。未配置任何凭据就 connectstart_ssl_client()会直接返回 -1日志提示rootCABuff NULL pskIdent NULL psKey NULL !insecure !useRootCABundle。证书解析失败确认 PEM 字符串以-----BEGIN CERTIFICATE-----开头并完整结束解析失败时底层会释放对应证书结构防止堆内存泄漏见 ssl_client.cpp 的注释。connect返回 0 但原因不明使用lastError()读取 mbedTLS 错误码底层日志log_e会附带错误号与可读描述ssl_client.cpp。证书有效期问题根证书会随 CA 更新而轮换若固件生命周期较长可考虑 TOFU 或证书包方案而非硬编码单一根证书。综上NetworkClientSecure在单一类接口下完整覆盖了 HTTPS 客户端、mTLS 双向认证、PSK MQTT、STARTTLS 协议升级与证书指纹校验等主流安全连接场景结合 ssl_client.cpp 底层的 mbedTLS 调用链开发者可以在掌握实操 API 的同时理解每次握手的验证逻辑与内存管理细节从而为 ESP32 项目选择最合适的安全策略。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
