Background

wao.io uses TLS to secure communication to origin servers. TLS provides data encryption, message integrity and authenticity between communicating parties.

TLS requires to check a server certificates against a list of Certificate

Authorities (CA) that are considered trustworthy. The certificate must be issued for the server name that is used for the https://
request, and it is only considered valid before its expiration date. wao.io performs this checks by default.

There are several errors that are likely to occur during setup and use of a TLS connection. The WAO Error range from 2300 to 2399 is reserved for this kind of problems.

Do I have a TLS error?

If TLS errors occur between wao.io and the origin the sites stops working. Usually every request using HTTPS is affected. (However, the site may still work using the http:// protocol.)

In this case an error page is presented to the user since no content could be loaded from the origin servers.

Every error page is sent with a special HTTP response header field WAO-Error that contains an error code and an informative but non-disclosing error message.

Fixing the error

To restore the normal function of an affected site, here are the steps to be
taken for the different error codes.

2300 - "TLSError"

This error is the fallback for all TLS errors that are not covered by a more specific error code.

Actions:

  1. Check whether you can establish an HTTPS connection to the origin directly, bypassing wao.io. You can find the origin information in your site settings.

    Given the origin is available at the IP address 1.2.3.4 and the name of the site is example.com, you can use curl to check connectivity:

    curl -v --resolve example.com:443:1.2.3.4 https://example.com/

    The output of the program may give you hints what is wrong.
  2. Contact the wao.io team for help and further analysis.

2301 - "TLSHandshakeTimeout"

wao.io could not establish a TLS connection to the origin until the connect timeout of 15 seconds was reached.

Actions:

  1. Check if there origin is up and running. A handshake timeout may occur alongside other timeout errors, if the origin is unresponsive. In this case fix any ConnectionTimeout errors first.
  2. Check the performance of the origin. Is the server under heavy load?
  3. Possibly, the load balancer or web server that terminates TLS at the origin has not enough entropy. On Linux systems the remaining bits of the entropy pool can be read out in this way:

    cat /proc/sys/kernel/random/entropy_avail

    The returned value should not be too low. A full entropy pool has a default length of 4096 bits.

2302 - "TLSCertExpired"

SSL certificates are only issued for a certain period of time. After the expiry date, every TLS handshake will fail.

Actions:

  1. Workaround: Check if turning off the TLS check in wao.io brings the site back online:
    Site settings → Site → Domain → Advanced → Ignore Backend TLS certificate errors
  2. Obtain and install a new certificate in the origin server
  3. Undo the workaround from step 1

2303 - "TLSCertNameMismatch"

The certificate installed in the origin is not issued for the domain name that wao.io uses to request the origin.

Actions:

  1. Check if a change of the host header fixes the error
    Site settings → Site → Domain → Basic Settings → how should wao.io talk to the origin
    This field is used for SNI. If your origin accepts more than one domain name or Host header, chose one that is
    listed in your certificate.
  2. Workaround: Check if turning off the TLS check in wao.io brings the site back online:
    Site settings → Site → Domain → Advanced → Ignore Backend TLS certificate errors
  3. Obtain and install a new certificate in the origin server
  4. Undo the workaround from step 2

2304 - "TLSCertNotTrusted"

The certificate installed in origin has not been issued by a Certificate
Authority (CA) that wao.io trusts. Wao.io uses the CA bundle provided by the Linux distribution Debian.

Actions:

  1. Workaround: Check if turning off the TLS check in wao.io brings the site back online:
    Site settings → Site → Domain → Basic Settings → how should wao.io talk to the origin
  2. Obtain and install a new certificate in the origin server
  3. Undo the workaround from step 1

2305 - "TLSHandshakeError"

An error occurred during setup of the TLS connection. This may be because the origin only offers obsolete encryption methods or ciphers that are classified as unsafe and are not accepted by wao.io. It is also possible that the origin offers too many ciphers and so exceeds a maximum length.

Actions:

  1. Try to establish a TLS connection to your origin directly, e.g. using curl (cf. 2300) or the openssl command line tool.  If this works, contact the wao.io support for further debugging.
  2. Adjust your server's TLS parameters. We recommend to use TLS v1.2 or newer. The Mozilla Server-Side-TLS page is
    great resource for TLS settings.

Workaround: If your site does not demand secure communication (no logins, no private data, no session cookies, no shopping…) you may switch to HTTP traffic to bring your site back online.

Site settings → Site → Domain

  • in Basic Setup,  set Backend protocols to talk only HTTP to my origin domain,
  • in Security, disable Redirect HTTP URLs to HTTPS and Rewrite HTTP URLs to HTTPS

If you have had HTTP redirects enabled before, clients may still try to go to your https:// site, because "permanent" redirects (status code 301) may be cached forever. If you have sent a Strict-Transport-Security header, this workaround should not be your choice. Clients will still try to use the HTTPS site.

Did this answer your question?