TLS Error with Ruby Client and Tomcat Server

Temporarily work around the problem with a simple client-side hack.

If your Ruby is compiled against a recent version of OpenSSL (1.0.0 and up), there is a good chance you will run into frustrating TLS errors when trying to connect to an HTTPS site hosted by Apache Tomcat. An easy workaround is to set ssl_version = :SSLv3 on the client side.

Update: The better solution is to reconfigure Tomcat, because SSLv3 is known to be vulnerable to attacks. Proceed with caution!

Who’s affected?

Trouble happens when your Ruby is compiled against OpenSSL 1.0 and you try connecting to a Tomcat 7 server using HTTPS. Here’s how to check on your Ruby installation:

$ ruby -r openssl -e 'puts OpenSSL::OPENSSL_VERSION'
OpenSSL 1.0.0e 6 Sep 2011

When you connect to an affected Tomcat 7 server, you’ll be greeted with a vague tlsv1 alert internal error error that looks something like this:

SSL_connect returned=1 errno=0 state=SSLv2/v3 read server hello A: tlsv1 alert internal error

An easy workaround

If you control the Tomcat server, you can modify Tomcat’s configuration to restrict the ciphers Tomcat uses and eliminate the problem.

Otherwise, working around the problem on the client side in Ruby is straightforward. When using Net::HTTP, just set ssl_version = :SSLv3:1

http =, port)
http.use_ssl = true
http.ssl_version = :SSLv3
http.start { ... }

The same trick also works with the net-http-persistent gem:

http =
http.ssl_version = :SSLv3

  1. Always using SSLv3 is not a general-purpose solution. For best security, you want to stick with Ruby’s default, which is to try TLSv1 before falling back to older versions. Unfortunately, this particular SSL-Tomcat bug breaks the normal automatic fallback. Use this explicit SSLv3 workaround only after you’ve explored other options for fixing the issue on the Tomcat side. 

You just read

Temporarily work around the problem with a simple client-side hack.

May 2012

Share this post?  Copy link

About the author

Hi! I’m a Ruby and CSS enthusiast, regular open source contributor, software engineer, and occasional blogger writing from the San Francisco Bay Area. Thanks for stopping by! —Matt

GitHub Email LinkedIn