Why does an encrypted tunnel fail its TLS handshake after I upgrade QGTunnel?

Starting with version 2.8.0, QGTunnel is built with a current Go release and follows its TLS defaults. These are stricter than the defaults in version 2.7.7 and earlier. A small number of older destination servers that 2.7.7 connected to are refused by 2.8.0 unless you turn on one setting.

This page explains who is affected, how to recognize it, and how to restore the previous behavior.

Who is affected

Only tunnels that have encrypted = true in the .qgtunnel file, or the Encrypted box checked in the dashboard. On these tunnels QGTunnel itself makes the TLS connection to your destination.

You are not affected if:

  • Your tunnels do not use encrypted. This is the usual setup for databases, where your application or database driver does its own TLS through the tunnel. Nothing changed for these tunnels.
  • Your destination supports current TLS. Most do. QGTunnel connects to it exactly as before.

What changed

Version 2.8.0 refuses three things that version 2.7.7 accepted on encrypted tunnels:

Your destination What you see in the QGTunnel log
Supports only RSA key exchange (no ECDHE and no TLS 1.3) TLS Handshake error: remote error: tls: handshake failure
Is a TLS 1.2 server that can only sign its handshake with SHA-1 TLS Handshake error: remote error: tls: handshake failure
Presents a certificate with a negative serial number TLS Handshake error: tls: failed to parse certificate from server: x509: negative serial number

After any of these, QGTunnel also logs a line that names the setting below.

All three are properties of older or non-standard servers. Nothing changed in how QGTunnel connects to the QuotaGuard proxy.

How to restore the previous behavior

Set this environment variable where QGTunnel runs, then restart your application:

QGTUNNEL_LEGACY_TLS=true

On Heroku:

heroku config:set QGTUNNEL_LEGACY_TLS=true

With the setting on, QGTunnel accepts all three cases above again.

What the setting does

  • It only widens what QGTunnel accepts. A destination that supports current TLS still negotiates current TLS. It is safe to turn on when you have a mix of old and new destinations.
  • It applies to encrypted tunnels only.
  • It does not change the connection between QGTunnel and the QuotaGuard proxy.
  • It does not change how your own application does TLS. Your application’s environment is passed through as it was.
  • It does not bring back TLS 1.0, TLS 1.1, 3DES, or certificates signed with SHA-1. Version 2.7.7 already refused those.

The better long-term fix

The setting keeps an older server working. It does not make that connection any stronger. If you control the destination, or can ask its operator, the lasting fix is on the server:

  • Enable ECDHE cipher suites or TLS 1.3.
  • Allow SHA-256 signatures in the TLS handshake.
  • Reissue the certificate with a positive serial number.

Once the server is updated you can remove the setting.

How to check a destination

From a machine that is allowed to reach the destination, this shows whether it accepts a modern key exchange:

openssl s_client -connect HOST:PORT -servername HOST -tls1_2 -cipher 'ECDHE' </dev/null

If that fails with a handshake failure and the same command with -cipher 'kRSA' succeeds, the server supports RSA key exchange only.

This prints the certificate serial number. A leading minus sign means it is negative:

openssl s_client -connect HOST:PORT -servername HOST </dev/null 2>/dev/null | openssl x509 -noout -serial

Many destinations only answer the static IP addresses of your QuotaGuard subscription. In that case run the commands from a host that is on the destination’s allowlist.

Staying on the previous version

Every QGTunnel release stays available under its own version number. If you would rather not change anything yet, pin version 2.7.7 as described under Pinning a version on the changelog page.

Other changes in 2.8.0 that may matter to you

  • The macOS downloads require macOS 13 or later. Version 2.7.7 ran on macOS 11.
  • The Linux downloads require Linux kernel 3.2 or later.
  • The wording of some log lines for failed proxy connections changed. Each line still begins with Unable to dial.

Ready to Get Started?

Get in touch or create a free trial account

Back to top ↑

Copyright © 2009 - 2026 QuotaGuard. All rights reserved.