Debug MQTT TLS and mTLS Connections on iOS

Why MQTT TLS Connections Fail—and How to Tell Them Apart

MQTT over TLS fails at several distinct layers, each with its own symptoms. An expired certificate or incomplete chain causes the TLS handshake to abort before a single MQTT byte is sent. A hostname or SAN mismatch fails identically at the TLS layer but for a different reason—the broker’s certificate does not cover the hostname or IP you dialed. An untrusted or self-signed CA fails because the client refuses to anchor trust. Wrong or absent ALPN protocol negotiation causes AWS IoT Core and other load-balanced brokers to reject the connection silently after TLS completes. An unsupported TLS version (e.g., a broker that requires TLS 1.2 when the client tries 1.3, or vice versa) causes a protocol_version alert. Because these errors all present as a single opaque connection failure in most clients, the only reliable way to isolate the layer is staged diagnostics—exactly what Connection Doctor provides.

Staged Diagnostics: Isolating the Failing Layer

Connection Doctor runs through DNS resolution, TCP reachability, TLS handshake, optional mTLS client-certificate exchange, and MQTT CONNECT/CONNACK in sequence. Each stage either passes or stops with a typed, plain-language diagnosis—for example “TLS handshake failed: server certificate is not trusted. The broker’s CA is not in the system trust store and no custom CA was imported.” This eliminates the guesswork of correlating cryptic errSSL* codes against broker logs. The diagnostic bundle, with all secrets redacted, can be shared directly from the app for remote support without exposing credentials. Learn the full methodology in the TLS debugging guide.

Certificate Wizard: Import, Validate, and Configure in One Place

Certificate Wizard accepts .p12/.pfx bundles (with passphrase) and PEM files covering the CA certificate, client certificate, and private key. After import it immediately validates the chain, checks expiry, and confirms that the Subject Alternative Names or Common Name cover the hostname you are connecting to. SHA-256 fingerprints are displayed so you can cross-check against the broker. For mutual TLS the wizard stores both the CA trust anchor and the client identity; all key material is kept in the iOS Keychain and never leaves the device. ALPN configuration—including x-amzn-mqtt-ca for AWS IoT Core port 443—and SNI override are set per-connection without touching the certificate itself.

Mutual TLS (mTLS) Step by Step

mTLS requires the broker to trust your client certificate and the client to trust the broker’s CA. A common mistake is importing the client certificate without importing the CA, or importing the CA to the wrong profile. Certificate Wizard keeps them explicitly separate so each role is unambiguous. Once both are imported, Connection Doctor’s staged run will show TLS completing successfully and then report any MQTT-layer rejection (bad credentials, ACL, etc.) as a separate, clearly labeled stage. This separation is what makes mTLS debugging tractable: you know the TLS handshake succeeded before you start investigating broker-side authorization. MQTT Commander supports mTLS on TCP-with-TLS (mqtts://), WebSocket-with-TLS (wss://), and all MQTT 3.1.1 and MQTT 5 variants.

Reading MQTT 5 CONNACK Reason Codes After TLS Succeeds

Once the TLS layer is healthy, broker-side rejections surface as MQTT CONNACK reason codes. MQTT 5 defines over two dozen codes; the most common in TLS deployments are 0x87 (Not Authorized—often an mTLS client-certificate not mapped to an ACL policy), 0x85 (Client Identifier Not Valid), and 0x8D (Keep Alive Timeout). Connection Doctor decodes each code to a human-readable description and suggests the most likely fix—so you never need to cross-reference the specification manually. For MQTT 3.1.1 brokers the tool maps the equivalent numeric return codes (0–5) to the same plain-language output.