If you’ve experienced issues related to SSL certificates and/or TLS versions, you’ve cometo the right place. In this guide, we’ll explain how both of those issues come about and howto solve them. Many of the instructions in this guide can help fix either the SSL certs issueor the TLS version issue.

• That's Tiger.So starting with Tiger all the way through Mac OS 10.8 which is Mountain Lion.Version 1.8 is pre-installed and ready to go.Now most cases that's version 1.87.But there's a big problem with all of these 1.8 versions.And that is that they're no longer supported.And when I said that, I don't just mean that they won't.
• Install the MySQL RubyGems to allow Ruby code to communicate with a MySQL server. Let's try and deal with problem head-on and make sure that it works so that we don't have problems later. Instead of just installing it with our project we're going to install it globally as a RubyGem for all of our projects to use.

If you’re not interested in the reasons, and just want to get things fixed as quickly aspossible, you can jump straight to solutions for SSL issues.

3 Mac OS X comes with a version of Ruby preinstalled; check the version by typing ruby -version at the command prompt: $ ruby -version ruby 2.0.0p481 (2014-05-08 revision 45883) universal.x8664-darwin14 In this example, the version of Ruby is 2.0.0, and the number following the letter p is the current patch or build number. Newer versions.

Table of Contents

• The Problems
  • Why am I seeing certificate verify failed?
  • Why am I seeing read server hello A?
• The Solutions
  • Updating CA certificates
  • Reinstalling Ruby from version managers
  • Reinstalling Ruby from OS package managers
• Additional Help

The Problems

Why am I seeing certificate verify failed?

If you’ve seen the following SSL error when trying to pull updates from RubyGems:OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

This error happens when your computer is missing a file that it needs to verify that the serverbehind RubyGems.org is the correct one.

The latest version of RubyGems should fix this problem, so we recommend updating to the currentversion. To tell RubyGems to update itself to the latest version, run gem update --system. Ifthat doesn’t work, try the manual update process below.

(What do we mean by updating “should fix this problem”? Review the What are these certificates?and How Ruby uses CA certificates sectionsbelow to gain a better understanding of the underlying problems.)

What are these certificates?

Anytime your computer is talking to a server using HTTPS, it uses an SSL certificate as partof that connection. The certificate allows your computer to know that it is talking to the realserver for a domain, and allows it to make sure that your computer and that server cancommunicate completely privately, without any other computer knowing what is sent back and forth.

To know if the certificate for RubyGems.org is correct, your computer consults anothercertificate from a Certificate Authority (CA). The CA certificate bundle includes certificatesfrom every company that provides SSL certificates for servers, like Verisign, Globalsign, andmany others.

Each CA has a “root” certificate that they use to verify other certificates. The CA certificatesare called “root” because they sign other certificates that sign yet other certificates, and agraph of the certificates would look like a tree, with the “root” certificates at the root ofthe tree. Your computer will use its built-in CA bundle of many root certificates to knowwhether to trust an SSL certificate provided by a particular website, such as RubyGems.org.

Occasionally, new companies are added to the CA bundle, or existing companies have their certificatesexpire and need to distribute new ones. For most websites, this isn’t a hugeproblem, because web browsers regularly update their CA bundle as part of general browserupdates.

How Ruby uses CA certificates

The SSL certificate used by RubyGems.org descends from a new-ish root certificate. Ruby (andtherefore RubyGems and Bundler) does not have a regularly updated CA bundle to use whencontacting websites. Usually, Ruby uses a CA bundle provided by the operating system (OS). Onolder OSes, this CA bundle can be really old—as in a decade old. Since a CA bundle that oldcan’t verify the (new-ish) certificate for RubyGems.org, you might see the error in question:certificate verify failed.

Further complicating things, an otherwise unrelated change 18-24 months ago lead to a new SSLcertificate being issued for RubyGems.org. This meant the “root” certificate that needed toverify connections changed. So even if you’d previously upgraded RubyGems/Bundler in order tofix the SSL problem, you would need to upgrade again—this time to an even newer version witheven newer certificates.

Troubleshooting certificate errors

Start by running the automatic SSL check, and follow the instructions. You might needto update Bundler, update RubyGems,manually update RubyGems certificates, or perhapseven install new OS certificates.

Why am I seeing read server hello A?

This error means that your machine was unable to establish a secure connection to RubyGems.org.The most common cause for that problem is a Ruby that uses an old version of OpenSSL. OpenSSL1.0.1, released March 12, 2012, is the minimum version required to connect toRubyGems.org, starting January 1, 2018.

To understand why that version is required, keep reading. To see instructions on how to updateOpenSSL and/or Ruby to fix the problem, skip to thetroubleshooting section.

SSL and TLS protocol versions

Secure connections on the internet use HTTPS,the secure version of HTTP. That security was originally provided by SSL, an acronymfor Secure Sockets Layer. Over time, researchers discovered flaws in SSL, and networkdevelopers responded with changes and fixes. After SSL 3.0, it was replaced by TLS, orTransport Layer Security.

Over time, TLS was also revised. TLS version 1.2, originally defined in 2011, and supportedby OpenSSL starting in 2012, is the current standard. In 2017, every version of SSL and TLSolder than TLS 1.2 has been found to have critical flaws that can be exploited by adetermined or knowledable adversary. As a result, security best practices suggest activelyblocking all versions of SSL, as well as TLS versions 1.0 and 1.1.

TLS 1.0 and 1.1 are deprecated

RubyGems.org uses a 3rd party CDN provider called Fastly, which letsusers all around the world download gems really quickly.

Last year, Fastly announced it will deprecate TLS versions 1.0 and 1.1 due to a mandatepublished by the PCI Security Standard Council.(Read more about this in Fastly’s blog post.)

As a result, RubyGems.org will require TLSv1.2 at minimum starting January 2018. This meansRubyGems.org and the gem command will no longer support versions of Ruby and OpenSSL that aredo not have support of TLS 1.2.

Troubleshooting protocol errors

To troubleshoot protocol connection errors, start by running the automatic SSL check,and follow the instructions. You might need to update Bundler,update RubyGems, or even reinstall Ruby (you can find reinstallationinstructions by version manageror package manager.)

The Solutions

Automated SSL check

First, run this script tocheck whether your errors result from the SSL certs issue or the TLS versions issue.

You can run the script immediately with this command (Windows 10 also):

$ curl -Lks 'https://git.io/rg-ssl' | ruby

If the output reads “Your Ruby can’t connect to rubygems.org because you are missing thecertificate” you have a certificate verification error, and need to update your certs.

If you instead see “Your Ruby can’t connect to rubygems.org because your version of OpenSSL istoo old” your OpenSSL version is old and incompatible with TLSv1.2, and you need to upgrade yourOpenSSL and/or recompile Ruby to use a newer version of SSL.

The instructions in this guide can help you troubleshoot both problems.

Updating Bundler

Update to the latest version of Bundler by running:

gem install bundler

Updating RubyGems

You might be able to upgrade RubyGems using the self-update command:

gem update --system

If that command fails, you can try downloading the latest RubyGems yourself and installing it, using these steps. In this example, we will be downloading and installing RubyGems 2.7.6. If the latest version of RubyGems has changed by the time you are reading this, you will need to change anyplace you see 2.7.6 to the version of RubyGems that you have downloaded.

Rubygems Issues For Mac Computers

1. Using your web browser, head to the Download RubyGems page, and download the gem version of the latest rubygems.
2. Once you’ve downloaded the gem, open Terminal.app on macOS, or Command Prompt with Ruby on Windows.
3. Change directories to your Downloads folder. On macOS, the command would be cd ~/Downloads. On Windows, it would be cd C:Users%USERNAME%Downloads.
4. Install the downloaded RubyGems upgrade gem by running gem install --local rubygems-update-2.7.6.gem.
5. Run the upgrade command update_rubygems.

You’re done! Run gem --version to verify that you are using the latest version of RubyGems.

Updating System Clock

If your system clock is set to a time in the past or future, your machine will not be able to establish a secure connection to RubyGems.org. To resolve the issue, you will need to set your system clock to the current time. In Linux, you can update the system clock by running sudo ntpdate ntp.ubuntu.com.

Here are other possible solutions for updating a system clock:

Cached

• macOS: Set the time and date on your Mac
• Ubuntu: Ubuntu Time Management
• Windows: Getting Windows 10 time to sync with a time server
• Vagrant: Correcting the system clock in Vagrant

Updating CA certificates

Installing new RubyGems certificates

If you’re unable to update RubyGems, you can manually add the certificate RubyGems needs. If youhave a version of RubyGems new enough (version 2.1.x and above) that can use those “vendored”certificates—and you install the certificate successfully—it will work without upgrading theRubyGems version.

Warning: These instructions will only add new certs; Ruby will be left untouched. To ensureyour Ruby version can use TLSv1.2, run the snippet again. If not, follow a different set ofinstructions in this guide for upgrading Ruby as well.

Step 1: Get the new trust certificate

Download the .pem file from this link: GlobalSignRootCA.pem

Then, find the downloaded file, and check to make sure the filename ends in .pem.(Note: Some browsers will change the extension to .txt, which will prevent this from working.So it’s important to make sure the file you downloaded ends in a .pem extension.)

Step 2: Locate RubyGems certificate directory in your installation

Next, you’ll want to find the directory where you installed Ruby in order to add the .pem file there.

On Windows:

Open your command line and type in:

C:>gem which rubygems

You’ll see output like this:

C:/Ruby21/lib/ruby/2.1.0/rubygems.rb

To open a window showing the directory we need to find, enter the path part up to the fileextension in the same window (but using backslashes instead). For example, based on the outputabove, you would run this command:

C:>start C:Ruby21libruby2.1.0rubygems

This will open an Explorer window, showing the directory RubyGems is installed into.

On macOS:

Open Terminal and run this command:

$ gem which rubygems

You’ll see output like this:

/opt/rubies/2.4.1/lib/ruby/2.4.0/rubygems.rb

To open a window showing the directory we need to find, use the open command on that outputwithout the “.rb” on the end, like this:

$ open /opt/rubies/2.4.1/lib/ruby/2.4.0/rubygems

A Finder window will open showing the directory that RubyGems is installed into.

Step 3: Copy new trust certificate

In the window, open the ssl_certs directory and drag your .pemfile into it. It will be listed with other files like AddTrustExternalCARoot.pem.

Once you’ve done this, it should be possible to follow the directions at the very top toautomatically update RubyGems. Visit the Update RubyGems section forstep-by-step instructions. If that doesn’t work, keep following this guide.

Installing new OS certificates

This solution might work when the version of OpenSSL installed with Homebrew interfereswith Ruby’s ability to find the correct certificates. Sometimes, uninstalling everything andstarting again from scratch is enough to fix things.

First, you’ll want to remove RVM. You can do that by running this command:

$ rvm implode

Next, you’ll want to remove OpenSSL from Homebrew. (Using --force ensures that you remove allversions of OpenSSL you might have):

$ brew uninstall openssl --force

Now, you can reinstall RVM, following the instructions from the previous step.

Reinstalling Ruby from version managers

Installed with rvm

Note: Try this solution if updating SSL certificates with RVM doesn’t work. If Rubyinstalled with RVM can’t find the correct certificates even after they have been updated, you might be able to fix it by reinstalling RVM and then reinstalling your Ruby version.

Run these commands to remove RVM and reinstall it:

$ rvm implode $ curl -sSL https://get.rvm.io | bash -s stable

Then, reinstall Ruby while telling RVM that you don’t want to use precompiled binaries.(Unfortunately, this will take longer, but it will hopefully fix the SSL problem.)

This command will install Ruby 2.2.3. Adjust the command to install the version(s) of Ruby that you need:

$ rvm install 2.2.3 --disable-binary

Installed with ruby-build or rbenv install

Follow the instructions outlined in the Updating and Troubleshooting ruby-build guide by rbenv.

Reinstalling Ruby from OS package managers

macOS: Built-in Ruby

macOS 10.13 High Sierra comes with default Ruby that is compatible with TLSv1.2.

To check your current macOS version, go to the Apple menu and choose “About This Mac”.If you see anything other than “macOS High Sierra”, you will need to upgrade to the newestmacOS (or else install a newer version of Ruby with Homebrew by following the next set ofinstructions after these).

To upgrade to High Sierra:- 1. Open the App Store application- 2. Choose the “Updates” tab- 3. Click the “Install” button for “macOS High Sierra”

macOS: Installed with Homebrew

Note: To install a newer version of Ruby with Homebrew, first make sure Homebrew is installed.If the brew command is not present, follow the installation instructions at https://brew.shand then come back to these steps.

• 1. Run brew update
• 1. Run brew install ruby
• 1. If Ruby is already installed, run brew upgrade ruby to upgrade to the latest version.

Debian or Ubuntu 16.04: Installed with apt-get

Note: To remove Ruby with apt, you’ll need to check which versions of Ruby you have installed.apt installs Ruby v2.3.1.

To uninstall, follow the directions listed here.(These instructions work for both Ubuntu and Debian.)

Once you’ve successfully uninstalled Ruby, reinstall it by running:

$ sudo apt-get install ruby

Fedora: Installed with dnf

Note: The newest versions of Fedora use dnf as its package manager, but older versionsuse yum instead. If you see the error message dnf: command not found, replace the dnfin these instructions with yum.

First, uninstall Ruby by running:

$ dnf remove ruby

And then reinstall (this command will install Ruby 2.3):

$ dnf install ruby

RHEL or CentOS: Installed with yum

Follow these directions for upgrading Ruby on CentOS.(They also include instructions for troubleshooting OpenSSL.)

Windows: Installed with Ruby Installer

From the Control Panel, find the Ruby installer in “Programs”. Click on the folder, and clickagain on “Uninstall Ruby”.Reinstall by downloading Ruby and the Ruby DevKit at RubyInstaller.

Additional Help

Running another automated SSL check

Rerun the automated SSL check to verify if the issue lies with an SSL issueor a TLS issue. If you’ve already followed the troubleshooting steps above and are stillencountering an issue, go to the creating an issue section below for next steps.

Creating an issue

If none of these instructions fixed the problem, the next step is to open an issue.

(Create an issue in the RubyGems issue trackerif your error came from gem install. If it came from bundle install, create an issue inthe Bundler issue tracker.)

Questions / Discussion Area - RubyGems.org Support

Please include:- The output from running gem env:- The output from running bundle env:- Output from running ruby -ropenssl -e 'puts OpenSSL::OPENSSL_LIBRARY_VERSION':- Your Ruby version manager (if any):- Your OS and OS version:- Your package manager name and version (if applicable):

Contributing to this guide

If you found a solution not listed here, submit a PR to add your solution to this guide!