Setting up SSL certificates

Stef Schenkelaars edited this page May 20, 2015 · 17 revisions
Clone this wiki locally

##Background and Setup

Faraday requires a little extra configuration for users who want to use SSL/HTTPS. Typically any log in, authentication, or payment processing will use HTTPS. Most systems will already have a Certificate Authority (CA) certificates bundle available already. Prior to performing SSL transactions, Faraday needs to know where the system's CA certificates are located. If Faraday is used for only HTTP, then no SSL setup is necessary. Otherwise, follow the steps below to set up the proper CA paths.

###Ubuntu To locate your SSL certificate folder, type openssl version -a. You should see a response similar to

OpenSSL 0.9.8o 01 Jun 2010
built on: Thu Feb 10 01:47:31 UTC 2011
platform: debian-amd64
options:  bn(64,64) md2(int) rc4(ptr,char) des(idx,cisc,16,int) blowfish(ptr2) 
compiler: cc -fPIC -DOPENSSL_PIC -DZLIB -DOPENSSL_THREADS -D_REENTRANT -DDSO_DLFCN -DHAVE_DLFCN_H -m64 -DL_ENDIAN -DTERMIO -O3 -Wa,--noexecstack -g -Wall -DMD32_REG_T=int -DOPENSSL_BN_ASM_MONT -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DMD5_ASM -DAES_ASM
OPENSSLDIR: "/usr/lib/ssl"

Append /certs to the OPENSSLDIR listed, here it would be /usr/lib/ssl/certs.

With this certs directory known, change your Faraday initializer to include this path as the ca_path variable.

connection = Faraday::Connection.new 'https://encrypted.google.com', :ssl => {
    :ca_path => "/usr/lib/ssl/certs"
}

The location of the certificates can also be set system wide by setting it in the environment, for example:

export SSL_CERT_FILE=/usr/lib/ssl/certs/ca-certificates.crt

HTTP requests using this object will now use that path for SSL certificates

connection.get '/search?q=asdf' # returns successful result

Heroku, Fedora, CentOS

Users report that on Heroku, Fedora and CentOS, they have to point to a specific file, like so (Heroku example displayed)

connection = Faraday::Connection.new 'https://encrypted.google.com', :ssl => {
    :ca_file => '/usr/lib/ssl/certs/ca-certificates.crt'}

For Fedora and CentOS, use the path and file /etc/pki/tls/certs/ca-bundle.crt instead, or find your system path with openssl version -a.

Error Messages

Users who don't set up the CA path or set it up incorrectly will see the following error when performing HTTPS transactions:

OpenSSL::SSL::SSLError (SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed):

This error can have 2 causes

  1. You do not have the proper SSL certificates on your system. This would be the case if no browser or other system application can view ssl sites.

    To test, open up https://encrypted.google.com/ in a browser. If it loads, your system has SSL certificates available. If not, you may be missing SSL certificates. This seems unlikely as most modern browsers install SSL certificates automatically.

    However, if this is the case, you may download an SSL certificates bundle from GoDaddy , which is a certificate authority. The specific file you will need depends on your web server.

  2. OpenSSL is unaware of where the SSL certificates are located on your system. See the background section above for information on setting up your Certificate Authority (CA) path.

#Solutions to avoid

Some online posts suggest disabling SSL with a command similar to the following:

conn = Faraday.new("<host>", { ssl: { verify: false } })

This will eliminate the certificate verify failed error. However, it is strongly discouraged in production code as you're weakening the encryption process by using unchecked security certificates. This will open up your site to multiple types of cryptographic attacks.