If you’re having problems with your SSL certificate and (or) the TLS version, you’ve come to the right place. In this guide, we’ll explain the causes of both of those problems and how to fix them. Many of the instructions in this article can help troubleshoot SSL certificate issues or TLS version issues. If you don’t mind the reason and just want to fix everything as quickly as possible, you can jump straight to solutions for SSL problems .
1. The problem
1.1 Why do I see the certificate verify failed error?
When you pull updates from RubyGems using gem update
or gem install <your_gem>
, … and get the following error:
OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
.
This error occurs when your computer is missing a file that it needs to verify that the server behind RubyGems.org is correct.
The latest version of RubyGems will fix this issue, so we recommend updating to current version. To have RubyGems update itself to the latest version, run gem update --system
. If that doesn’t work, try the manual update procedure below.
What does the “should fix this” update mean for us? Review What Are These Certifications? and the sections below How does Ruby use CA certificates? to better understand the basics.
1.1.1 What are these certificates?
Whenever your computer communicates with the server (server) using HTTPS, it will use the SSL certificate as part of that connection. The certificate lets your computer know that it is communicating with the real server for a domain and ensures that the communication between your computer and the server is completely private without any problems. Any other computer knows what to send back and forth.
To see if the certificate for RubyGems.org is correct, your computer references another certificate from the Certificate Authority (CA). The CA certificate package includes certificates from every company that offers SSL certificates for servers, like Verisign, Globalsign, and many others.
Each CA has a “root” certificate that is used to verify other certificates. CA certificates are called “root” because they sign other certificates (which can also sign other certificates). In other words, the diagram of the certificates will look like a tree, with the “root” certificates at the root of the tree.
Your computer will use the built-in CA package of multiple “root” certificates to know whether 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 certificates that expire and need to distribute new certificates. For most websites, this isn’t a big deal, because web browsers regularly update their CA bundles as part of general browser updates.
1.1.2 How Ruby uses CA certificates
The SSL certificate used by RubyGems.org is derived from the new root certificate. Ruby (and therefore RubyGems and Bundler) doesn’t have a CA bundle that is regularly updated for use when interacting with websites. Usually, Ruby uses a CA package provided by the operating system (OS). On older operating systems, this CA bundle can really get old – as in a decade. When an old CA bundle fails to verify (new-ish) the certificate for RubyGems.org , you may see an error in the question: certificate verify failed
.
Things get further complicated when another unrelated change 18-24 months ago resulted in a new SSL certificate being issued to RubyGems.org . This means the “roor” certificate is needed to verify connections have changed. So even if you previously upgraded RubyGems / Bundler to fix the SSL issue, you’ll need to upgrade again – this time to a newer version with newer certificates.
1.1.3 Troubleshooting Certificate Errors
Start by running an automated SSL check and follow the instructions. You might need to update Bundler, update RubyGems, manually update RubyGems certificate, or maybe even install a new OS certificate.
1.2 Why do I see read server hello A?
This error means your machine is unable to establish a secure connection to RubyGems.org . The most common cause for that problem is a Ruby using an older version of OpenSSL. OpenSSL 1.0.1, released March 12, 2012, is the minimum version required to connect to RubyGems.org , starting January 1, 2018.
To understand why that version is needed, keep reading. For instructions on how to update OpenSSL and / or Ruby to fix the problem, go to the troubleshooting section.
1.2.1 Protocol versions SSL and TLS
Secure connections on the internet use HTTPS, the secure version of HTTP. That security was originally provided by SSL, which stood for Secure Sockets Layer. Over time, researchers discovered vulnerabilities in SSL, and network developers responded with changes and fixes. After SSL 3.0, it was replaced with TLS, or Transport Layer Security .
Over time, the TLS has also been revised. TLS version 1.2, originally defined in 2011 and supported by OpenSSL starting in 2012, is the current standard. In 2017, any versions of SSL and TLS older than TLS 1.2 were found to have critical vulnerabilities that could be exploited by a known or knowledgeable adversary. Therefore, best practices suggest proactively blocking all SSL versions, as well as TLS versions 1.0 and 1.1.
1.2.2 TLS 1.0 and 1.1 are deprecated
RubyGems.org uses a 3rd party CDN provider called Fastly , which allows users around the world to download gems really quickly.
Last year, Fastly announced that it would stop using TLS 1.0 and 1.1 versions due to the authorization announced by the PCI Security Standards Council. ( Read more about this in Fastly’s blog post .)
Hence, RubyGems.org will require at least TLSv1.2 starting January 2018. This means that RubyGems.org and gem
will no longer support Ruby and OpenSSL versions that do not support TLS 1.2.
1.2.3 Troubleshooting protocol errors
To fix the protocol connection error, start by running an automatic SSL test and following the instructions. You may need to update your Bundler, update RubyGems, or even reinstall Ruby (you can find instructions for reinstalling using a version manager or package manager.)
2. Solution
2.1 Automatic SSL Check
First, run this script to check if your error is caused by an SSL certificate issue or a TLS version issue.
You can run the script immediately using this command (including Windows 10):
1 2 | curl -Lks 'https://git.io/rg-ssl' | ruby |
If the output says “Your Ruby can’t connect to rubygems.org because you are missing the certificate” then you have a certificate verification error and need to update your certificate.
Instead, if you see the message “Your Ruby can’t connect to rubygems.org because your version of OpenSSL is too old” then your OpenSSL version is old and not compatible with TLSv1.2 and you need to upgrade. OpenSSL and / or recompile Ruby to use a newer version of SSL.
The instructions in this article can help you fix both problems.
2.2 Update bundle
Update to the latest Bundler version by running the command:
1 2 | gem install bundler |
2.3 Update RubyGems
You can upgrade RubyGems with the self-update command:
1 2 | gem update --system |
If the above command fails, you can try to manually download the latest RubyGems and install it using following steps. In this example, we will download and install RubyGems 2.7.6. If the latest version of RubyGems has changed by the time you are reading this article, you will need to change wherever you see 2.7.6 to the version RubyGems you downloaded.
- Step 1: Using your web browser, go to the Download RubyGems page and download the gems version of the latest rubygems.
- Step 2: Once you’ve downloaded the gem, open Terminal.app on macOS or Command Prompt with Ruby on Windows.
- Step 3: Change the folder to your Downloads folder. On macOS, the command will be
cd ~/Downloads
. On Windows, it will becd C:Users%USERNAME%Downloads
. - Step 4: Install gems to upgrade the downloaded RubyGems by running
gem install --local rubygems-update-2.7.6.gem
. Run theupdate_rubygems
update command.
It’s done! Run gem --version
to verify that you are on the latest version of RubyGems.
2.4 Updating System Clock
If your system clock is set to past or future time, your machine will not be able to establish a secure connection to RubyGems.org . To solve the problem, 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 to update the system clock:
- macOS: Set the date and time on your Mac
- Ubuntu: Ubuntu Time Management
- Windows: Gives Windows 10 time to sync with the time server
- Vagrant: Modifying the system clock in Vagrant
2.5 Update the CA certificate
2.5.1 Install a new RubyGems certificate
If you can’t update RubyGems, you can manually add a RubyGems certificate. If you have a new enough version of RubyGems (version 2.1.x or higher) you can use those “provided” certificates – and when the certificate is installed successfully it will work without lifting. RubyGems version level.
Warning: These instructions will only add a new certificate; Ruby will be preserved. To make sure your Ruby version can use TLSv1.2, run the code again. If not, follow the other set of instructions in this tutorial to upgrade Ruby.
Step 1: Get a new trusted certificate
Download the .pem file from this link: GlobalSignRootCA.pem
Then find the downloaded file and check to make sure the filename ends with .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 up with a .pem extension. )
Step 2: Locate the RubyGems certificate folder in your installation
Next, you’ll want to find the directory where you installed Ruby to add the .pem file to it.
On Windows, open your command line and type:
C:>gem which rubygems
You should see output like this:
C:/Ruby21/lib/ruby/2.1.0/rubygems.rb
To open a window showing the folder we are looking for, type the path up to the file extension in the same window (but use a backslash instead). For example, based on the output above, you would run this command:
C:>start C:Ruby21libruby2.1.0rubygems
This will open an Explorer window, showing the RubyGems folder it is installed in.
On macOS, open Terminal and run this command:
$ gem which rubygems
You should see output like this:
/opt/rubies/2.4.1/lib/ruby/2.4.0/rubygems.rb
To open a window showing the directory we are looking for, use the open command on that output with no “.rb” at the end, like so:
$ open /opt/rubies/2.4.1/lib/ruby/2.4.0/rubygems
A Finder window will open showing the folder where RubyGems is installed.
Step 3: Copy a new trusted certificate
In the window, open the ssl_certs folder and drag your .pem file into it. It will be listed with other files like AddTrustExternalCARoot.pem.
Once you’ve done this, you can follow the instructions above to automatically update RubyGems. Visit the RubyGems Updates section for step-by-step instructions. If that doesn’t work, continue to follow this guide.
2.5.2 Install a new operating system certificate
This solution might work when the version of OpenSSL installed using Homebrew hinders Ruby’s ability to find the correct certificate. Sometimes, uninstalling everything and starting over is enough to fix everything.
First you will need to remove RVM. You can do that by running this command:
1 2 | $ rvm implode |
Next, you will need to remove OpenSSL from Homebrew. (Using --force
sure you delete all OpenSSL versions you might have):
1 2 | $ brew uninstall openssl --force |
You can now reinstall RVM, following the instructions below.
2.5.3 Reinstall Ruby from the version manager
Install with rvm
Note: Try this solution if updating SSL certificate with RVM doesn’t work. If Ruby installed using RVM can’t find the correct certificates even though they were up to date, you can fix it by reinstalling RVM and then reinstalling your version of Ruby.
Run the following commands to remove RVM and reinstall it:
1 2 | $ rvm implode $ curl -sSL https://get.rvm.io | bash -s stable |
Then reinstall Ruby while telling RVM that you don’t want to use pre-compiled binaries. (Unfortunately, this process will take longer, but hopefully it will fix the SSL issue.)
This command will install Ruby 2.2.3. Adjust the command to install the Ruby version (s) you need:
1 2 | $ rvm install 2.2.3 --disable-binary |
Install using ruby-build or rbenv install
Follow the instructions outlined in rbenv’s Update and Troubleshooting guide .
2.5.4 Reinstall Ruby from the operating system package manager
macOS: Ruby built in
macOS 10.13 High Sierra comes with Ruby by default which is compatible with TLSv1.2.
To check your current macOS version, go to the Apple menu and select “About This Mac”. If you see anything other than “macOS High Sierra” you will need to upgrade to the latest macOS (or if not, install a newer version of Ruby with Homebrew by following the next set of instructions. after these).
To upgrade to High Sierra:
- Open the App Store app
- Select the tab “Update”
- Click the “Install” button for “macOS High Sierra”
macOS: Installed using Homebrew
Note: To install a newer version of Ruby with Homebrew, first make sure that Homebrew is installed. If the brew command doesn’t appear, follow the installation instructions at https://brew.sh and then go back to these steps.
Run brew update
Run brew install ruby
If Ruby is already installed, run brew upgrade ruby
to upgrade to the latest version.
Debian or Ubuntu 16.04: Installed using apt-get
Note: To remove Ruby using apt, you need to check which Ruby version you have installed.
apt
install Ruby v2.3.1.
To uninstall, follow the instructions listed here. (These instructions work for both Ubuntu and Debian.)
Once you’ve successfully uninstalled Ruby, reinstall it by running:
1 2 | $ sudo apt-get install ruby |
Fedora: Installed using dnf
Note: The latest versions of Fedora use
dnf
as its package manager, but older versions useyum
instead. If you see the error messagednf
: command not found, replace dnf in these instructions withyum
.
First, uninstall Ruby by running:
1 2 | $ dnf remove ruby |
And then reinstall (this command will install Ruby 2.3):
1 2 | $ dnf install ruby |
RHEL or CentOS: Installed with yum
Follow these instructions to upgrade Ruby on CentOS . (They also include instructions for troubleshooting OpenSSL.)
Windows: Installed using Ruby Installer
From the Control Panel, find the Ruby installer in “Programs”. Click the folder and click “Uninstall Ruby” again. Reinstall by downloading Ruby and Ruby DevKit at RubyInstaller.
Additional help
Run another automatic SSL check
Rerun the automatic SSL test to verify if the problem is an SSL issue or a TLS problem. If you’ve followed the troubleshooting steps above and still have the problem, go to the troubleshooting section below for the next steps.
Create a problem
If none of these instructions fixed the problem, the next step is to open the problem.
(Create issue in RubyGems crash tracker if your error came from gem install
. If error is caused by bundle install
cause then create issue in Bundler issue tracker
Please include: – Output when running gem env
: – Output when running bundle env
: – Output when running ruby -ropenssl -e 'puts OpenSSL::OPENSSL_LIBRARY_VERSION'
: – Manager of your Ruby ruby -ropenssl -e 'puts OpenSSL::OPENSSL_LIBRARY_VERSION'
(if Yes): – Your operating system and OS version: – Your package manager name and version (if applicable):
Contribute to this article
If you find a solution not listed here, please submit a PR to add your solution to this guide or leave it in the comments below! I wish you a good day
References
The article was translated from the source How to troubleshoot RubyGems and Bundler TLS / SSL Issues . (In the process of translating the article, there is any incorrect or unsatisfactory translation in the comments section below)