NetBurner 3.5.0
PDF Version
 
SSL/TLS Troubleshooting

Troubleshooting Browser Warnings

There are multiple reasons why an SSL client like a web browser, command-line client like curl, or built-in library like OpenSSL or wolfSSL, might fail to connect and display a secure connection warning. There are many requirements for a secure, trusted connection with SSL:

  • Certificate must be issued by CA trusted by the client
    • If the certificate is self-signed, it must be manually installed on every client that connects otherwise a warning will be displayed saying that the certificate is not trusted.
    • This doesn't mean that the connection won't be encrypted, but rather that your client can't validate who you're talking to: if an attacker has redirected your connection to go through them, the client wouldn't be able to warn you any other way. An encrypted connection to an untrusted "Man in the Middle" wouldn't be ultimately considered very secure.
  • Enough of the CA certificate chain must be installed on both the client and server to form an adequate chain of trust
    • When installing trusted SSL server certificates or SSL client certificates, a CA certificate or certificate chain is usually provided alongside. This should also be installed using the server or client's documented process. For NetBurner, see Third-Party Certificate Authority.
  • Certificate name (CN or SAN) must match the hostname of the server
    • If a certificate is only issued for example.com or 10.1.1.77 but the client is accessing it via example.net or 10.1.1.66, a warning will be displayed that there is a mismatch.
  • Certificate expiration (Not After) time and issue (Not Before) time can't be after/before the client's clock.
    • This error is most often encountered when the client's clock isn't set properly; configuring and waiting for NTP before initiating SSL connections is the most common fix.
  • Certificate algorithm must be supported by the client and server (RSA, ECDSA, etc)
    • Some older clients or servers don't yet support ECDSA, but many CAs switched to ECDSA around 2022 so this should be a declining concern outside of legacy support.
  • Certificate can't be revoked. If the client's revocation list says the certificate is bad, you either need a new certificate or to troubleshoot the client's revocation list.

There are also a few SSL issues not directly relevant to the certificate which can cause warnings:

  • An SSL version can't be agreed upon by both client and server
    • Ex: if the server requires TLS 1.2+ but the client only supports 1.1 or lower. Note that "SSL" version numbers are all older than any TLS version number: the order is SSL2, SSL3, TLS1.0, TLS1.1, TLS1.2, TLS1.3, etc.)
  • An SSL cipher suite couldn't be agreed upon by both client and server
    • Each NetBurner NNDK release ships with and supports the default ciphers provided by wolfSSL, however over time old ciphers stop being trusted and new ciphers are released that may not be fully supported by all clients and servers. When there is no overlap between these supported ciphers, secure communication can no longer be established.
  • SSL negotiation process failed for an unknown reason
    • Maybe a bad connection, software failure, invalid cert/key format, or cert/key file permissions
  • Mixed content warnings or failures
    • If an HTML page is loaded via HTTPS but includes resources via HTTP, browsers may warn or fail to load that content for security reasons.
  • If a client previously accessed an IP or hostname via HTTPS, and HTTP Strict Transport Security was set on the server, the client will fail to connect to that host via HTTP.

An easy way to avoid most of these problems is to use our automated ACME certificate process if your device has a public IP and is accessible via a public DNS name.