While working with the ESP8266, I ran into a tricky issue with SSL handshakes failing unexpectedly. The problem turned out to be related to how the ESP8266 (and certain ESP-IDF versions) parse Subject Alternative Name (SAN) fields in certificates.
The Problem
The issue stems from the fact that all ESP-IDF versions using TCP_IP_ADAPTER.h struggle to parse SAN fields properly—especially when an IP address is used instead of a domain name (more details here). The ESP8266, using the older ESP-IDF v3.4 in its RTOS SDK, relies on this same header for TCP connections.
Initially, I had fixed some MQTT broker connection issues (with Raspberry Pi clients) by assigning an IP address in the broker’s SAN field. That worked for the Pi devices but caused every ESP8266 to fail the SSL handshake with this error:
The certificate Common Name (CN) does not match with the expected CN.
My Fix
The solution? I switched from using an IP address to a domain name for the Raspberry Pi. Thanks to the avahi-daemon running on the Pi, the domain name gets properly resolved by all devices on the local network.
This tweak not only fixed the ESP8266’s handshake problem but also smoothed out earlier connection hiccups I had encountered.
Final Thoughts
It’s one of those classic cases where a fix for one issue caused another—but luckily, the domain name approach proved to be the clean, long-term solution for both. If you're wrestling with similar SSL/TLS quirks on the ESP8266, I highly recommend avoiding IPs in your SAN fields altogether.