class HTTPClient::SSLConfig

Represents SSL configuration for HTTPClient instance. The implementation depends on OpenSSL.

Trust Anchor Control

SSLConfig loads 'httpclient/cacert.pem' as a trust anchor (trusted certificate(s)) with #add_trust_ca in initialization time. This means that HTTPClient instance trusts some CA certificates by default, like Web browsers. 'httpclient/cacert.pem' is downloaded from curl web site by the author and included in released package.

On JRuby, HTTPClient uses Java runtime's trusted CA certificates, not cacert.pem by default. You can load cacert.pem by calling #load_trust_ca manually like:

HTTPClient.new { self.ssl_config.load_trust_ca }.get("https://...")

You may want to change trust anchor by yourself. Call #clear_cert_store then #add_trust_ca for that purpose.

Constants

CIPHERS_DEFAULT

Attributes

cert_store[R]

OpenSSL::X509::X509::Store used for verification. You can reset the store with #clear_cert_store and set the new store with #cert_store=.

cert_store_crl_items[R]
cert_store_items[R]

These array keeps original files/dirs that was added to @cert_store

ciphers[R]

A String of OpenSSL's cipher configuration. Default value is ALL:!ADH:!LOW:!EXP:!MD5:+SSLv2:@STRENGTH See ciphers(1) man in OpenSSL for more detail.

client_cert[R]
OpenSSL::X509::Certificate

certificate for SSL client authentication.

nil by default. (no client authentication)

client_key[R]
OpenSSL::PKey::PKey

private key for SSL client authentication.

nil by default. (no client authentication)

client_key_pass[R]
options[R]

A number of OpenSSL's SSL options. Default value is OpenSSL::SSL::OP_ALL | OpenSSL::SSL::OP_NO_SSLv2 CAUTION: this is OpenSSL specific option and ignored on JRuby. Use #ssl_version to specify the TLS version you want to use.

ssl_version[R]

Which TLS protocol version (also called method) will be used. Defaults to :auto which means that OpenSSL decides (In my tests this resulted with always the highest available protocol being used). String name of OpenSSL's SSL version method name: TLSv1_2, TLSv1_1, TLSv1, SSLv2, SSLv23, SSLv3 or :auto (and nil) to allow version negotiation (default). See {OpenSSL::SSL::SSLContext::METHODS} for a list of available versions in your specific Ruby environment.

timeout[R]

SSL timeout in sec. nil by default.

verify_callback[R]

A callback handler for custom certificate verification. nil by default. If the handler is set, handler.call is invoked just after general OpenSSL's verification. handler.call is invoked with 2 arguments, ok and ctx; ok is a result of general OpenSSL's verification. ctx is a OpenSSL::X509::StoreContext.

verify_depth[R]

A number of verify depth. Certification path which length is longer than this depth is not allowed. CAUTION: this is OpenSSL specific option and ignored on JRuby.

verify_mode[R]

A number which represents OpenSSL's verify mode. Default value is OpenSSL::SSL::VERIFY_PEER | OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT.

Public Class Methods

new(client) click to toggle source

Creates a SSLConfig.

# File lib/httpclient/ssl_config.rb, line 96
def initialize(client)
  return unless SSLEnabled
  @client = client
  @cert_store = X509::Store.new
  @cert_store_items = [:default]
  @cert_store_crl_items = []
  @client_cert = @client_key = @client_ca = nil
  @verify_mode = SSL::VERIFY_PEER | SSL::VERIFY_FAIL_IF_NO_PEER_CERT
  @verify_depth = nil
  @verify_callback = nil
  @dest = nil
  @timeout = nil
  @ssl_version = :auto
  # Follow ruby-ossl's definition
  @options = OpenSSL::SSL::OP_ALL
  @options &= ~OpenSSL::SSL::OP_DONT_INSERT_EMPTY_FRAGMENTS if defined?(OpenSSL::SSL::OP_DONT_INSERT_EMPTY_FRAGMENTS)
  @options |= OpenSSL::SSL::OP_NO_COMPRESSION if defined?(OpenSSL::SSL::OP_NO_COMPRESSION)
  @options |= OpenSSL::SSL::OP_NO_SSLv2 if defined?(OpenSSL::SSL::OP_NO_SSLv2)
  @options |= OpenSSL::SSL::OP_NO_SSLv3 if defined?(OpenSSL::SSL::OP_NO_SSLv3)
  # OpenSSL 0.9.8 default: "ALL:!ADH:!LOW:!EXP:!MD5:+SSLv2:@STRENGTH"
  @ciphers = CIPHERS_DEFAULT
  @cacerts_loaded = false
end

Public Instance Methods

add_crl(crl) click to toggle source

Adds CRL for verification.

crl

a OpenSSL::X509::CRL or a filename of a PEM/DER formatted OpenSSL::X509::CRL.

On JRuby, instead of setting CRL by yourself you can set following options to let HTTPClient to perform revocation check with CRL and OCSP: -J-Dcom.sun.security.enableCRLDP=true -J-Dcom.sun.net.ssl.checkRevocation=true ex. jruby -J-Dcom.sun.security.enableCRLDP=true -J-Dcom.sun.net.ssl.checkRevocation=true app.rb

Revoked cert example: test-sspev.verisign.com:2443/test-SSPEV-revoked-verisign.html

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 241
def add_crl(crl)
  unless crl.is_a?(X509::CRL)
    crl = X509::CRL.new(File.open(crl) { |f| f.read })
  end
  @cert_store.add_crl(crl)
  @cert_store_crl_items << crl
  @cert_store.flags = X509::V_FLAG_CRL_CHECK | X509::V_FLAG_CRL_CHECK_ALL
  change_notify
end
Also aliased as: set_crl
add_trust_ca(trust_ca_file_or_hashed_dir) click to toggle source

Sets trust anchor certificate(s) for verification.

trust_ca_file_or_hashed_dir

a filename of a PEM/DER formatted OpenSSL::X509::Certificate or a 'c-rehash'eddirectory name which stores trusted certificate files.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 206
def add_trust_ca(trust_ca_file_or_hashed_dir)
  @cacerts_loaded = true # avoid lazy override
  add_trust_ca_to_store(@cert_store, trust_ca_file_or_hashed_dir)
  @cert_store_items << trust_ca_file_or_hashed_dir
  change_notify
end
Also aliased as: set_trust_ca
add_trust_ca_to_store(cert_store, trust_ca_file_or_hashed_dir) click to toggle source
# File lib/httpclient/ssl_config.rb, line 214
def add_trust_ca_to_store(cert_store, trust_ca_file_or_hashed_dir)
  if FileTest.directory?(trust_ca_file_or_hashed_dir)
    cert_store.add_path(trust_ca_file_or_hashed_dir)
  else
    cert_store.add_file(trust_ca_file_or_hashed_dir)
  end
end
cert_store=(cert_store) click to toggle source

Sets new certificate store (OpenSSL::X509::Store). don't use if you don't know what it is.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 192
def cert_store=(cert_store)
  @cacerts_loaded = true # avoid lazy override
  @cert_store = cert_store
  @cert_store_items.clear
  change_notify
end
ciphers=(ciphers) click to toggle source

Sets cipher configuration. New value must be a String.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 298
def ciphers=(ciphers)
  @ciphers = ciphers
  change_notify
end
clear_cert_store() click to toggle source

Drops current certificate store (OpenSSL::X509::Store) for SSL and create new one for the next session.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 181
def clear_cert_store
  @cacerts_loaded = true # avoid lazy override
  @cert_store = X509::Store.new
  @cert_store_items.clear
  change_notify
end
client_cert=(client_cert) click to toggle source

Sets certificate (OpenSSL::X509::Certificate) for SSL client authentication. #client_key and #client_cert must be a pair.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 132
def client_cert=(client_cert)
  @client_cert = client_cert
  change_notify
end
client_key=(client_key) click to toggle source

Sets private key (OpenSSL::PKey::PKey) for SSL client authentication. #client_key and #client_cert must be a pair.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 141
def client_key=(client_key)
  @client_key = client_key
  change_notify
end
default_verify_callback(is_ok, ctx) click to toggle source

Default callback for verification: only dumps error.

# File lib/httpclient/ssl_config.rb, line 363
def default_verify_callback(is_ok, ctx)
  if $DEBUG
    if is_ok
      warn("ok: #{ctx.current_cert.subject.to_s.dump}")
    else
      warn("ng: #{ctx.current_cert.subject.to_s.dump} at depth #{ctx.error_depth} - #{ctx.error}: #{ctx.error_string} in #{ctx.chain.inspect}")
    end
    warn(ctx.current_cert.to_text)
    warn(ctx.current_cert.to_pem)
  end
  if !is_ok
    depth = ctx.error_depth
    code = ctx.error
    msg = ctx.error_string
    warn("at depth #{depth} - #{code}: #{msg}") if $DEBUG
  end
  is_ok
end
load_trust_ca() click to toggle source

Loads default trust anchors. Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 224
def load_trust_ca
  load_cacerts(@cert_store)
  change_notify
end
options=(options) click to toggle source

Sets SSL options. New value must be a combination of # constants OpenSSL::SSL::OP_*

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 290
def options=(options)
  @options = options
  change_notify
end
sample_verify_callback(is_ok, ctx) click to toggle source

Sample callback method: CAUTION: does not check CRL/ARL.

# File lib/httpclient/ssl_config.rb, line 383
def sample_verify_callback(is_ok, ctx)
  unless is_ok
    depth = ctx.error_depth
    code = ctx.error
    msg = ctx.error_string
    warn("at depth #{depth} - #{code}: #{msg}") if $DEBUG
    return false
  end

  cert = ctx.current_cert
  self_signed = false
  ca = false
  pathlen = nil
  server_auth = true
  self_signed = (cert.subject.cmp(cert.issuer) == 0)

  # Check extensions whatever its criticality is. (sample)
  cert.extensions.each do |ex|
    case ex.oid
    when 'basicConstraints'
      /CA:(TRUE|FALSE), pathlen:(\d+)/ =~ ex.value
      ca = ($1 == 'TRUE')
      pathlen = $2.to_i
    when 'keyUsage'
      usage = ex.value.split(/\s*,\s*/)
      ca = usage.include?('Certificate Sign')
      server_auth = usage.include?('Key Encipherment')
    when 'extendedKeyUsage'
      usage = ex.value.split(/\s*,\s*/)
      server_auth = usage.include?('Netscape Server Gated Crypto')
    when 'nsCertType'
      usage = ex.value.split(/\s*,\s*/)
      ca = usage.include?('SSL CA')
      server_auth = usage.include?('SSL Server')
    end
  end

  if self_signed
    warn('self signing CA') if $DEBUG
    return true
  elsif ca
    warn('middle level CA') if $DEBUG
    return true
  elsif server_auth
    warn('for server authentication') if $DEBUG
    return true
  end

  return false
end
set_client_cert_file(cert_file, key_file, pass = nil) click to toggle source

Sets certificate and private key for SSL client authentication.

cert_file

must be a filename of PEM/DER formatted file.

key_file

must be a filename of PEM/DER formatted file. Key must be an RSA key. If you want to use other PKey algorithm, use #client_key=.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 153
def set_client_cert_file(cert_file, key_file, pass = nil)
  @client_cert, @client_key, @client_key_pass = cert_file, key_file, pass
  change_notify
end
set_crl(crl)
Alias for: add_crl
set_default_paths() click to toggle source

Sets OpenSSL's default trusted CA certificates. Generally, OpenSSL is configured to use OS's trusted CA certificates located at /etc/pki/certs or /etc/ssl/certs. Unfortunately OpenSSL's Windows build does not work with Windows Certificate Storage.

On Windows or when you build OpenSSL manually, you can set the CA certificates directory by SSL_CERT_DIR env variable at runtime.

SSL_CERT_DIR=/etc/ssl/certs ruby -rhttpclient -e "..."

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 169
def set_default_paths
  @cacerts_loaded = true # avoid lazy override
  @cert_store = X509::Store.new
  @cert_store.set_default_paths
  @cert_store_items = [ENV['SSL_CERT_FILE'] || :default]
  change_notify
end
set_trust_ca(trust_ca_file_or_hashed_dir)
Alias for: add_trust_ca
ssl_version=(ssl_version) click to toggle source

Sets SSL version method String. Possible values: “SSLv2” for SSL2, “SSLv3” for SSL3 and TLS1.x, “SSLv23” for SSL3 with fallback to SSL2.

# File lib/httpclient/ssl_config.rb, line 122
def ssl_version=(ssl_version)
  @ssl_version = ssl_version
  change_notify
end
timeout=(timeout) click to toggle source

Sets SSL timeout in sec.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 281
def timeout=(timeout)
  @timeout = timeout
  change_notify
end
verify_callback=(verify_callback) click to toggle source

Sets callback handler for custom certificate verification. See verify_callback.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 273
def verify_callback=(verify_callback)
  @verify_callback = verify_callback
  change_notify
end
verify_depth=(verify_depth) click to toggle source

Sets verify depth. New value must be a number.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 264
def verify_depth=(verify_depth)
  @verify_depth = verify_depth
  change_notify
end
verify_mode=(verify_mode) click to toggle source

Sets verify mode of OpenSSL. New value must be a combination of constants OpenSSL::SSL::VERIFY_*

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 256
def verify_mode=(verify_mode)
  @verify_mode = verify_mode
  change_notify
end

Private Instance Methods

change_notify() click to toggle source
# File lib/httpclient/ssl_config.rb, line 436
def change_notify
  @client.reset_all
  nil
end
load_cacerts(cert_store) click to toggle source

Use 2014 bit certs trust anchor if possible. CVE-2015-1793 requires: OpenSSL >= 1.0.2d or OpenSSL >= 1.0.1p OpenSSL before 1.0.1 does not have CVE-2015-1793 problem

# File lib/httpclient/ssl_config.rb, line 444
def load_cacerts(cert_store)
  ver = OpenSSL::OPENSSL_VERSION
  if (ver.start_with?('OpenSSL 1.0.1') && ver >= 'OpenSSL 1.0.1p') ||
      (ver.start_with?('OpenSSL ') && ver >= 'OpenSSL 1.0.2d') || defined?(JRuby)
    filename = 'cacert.pem'
  else
    warning("RSA 1024 bit CA certificates are loaded due to old openssl compatibility")
    filename = 'cacert1024.pem'
  end
  file = File.join(File.dirname(__FILE__), filename)
  unless defined?(JRuby)
    # JRuby uses @cert_store_items
    add_trust_ca_to_store(cert_store, file)
  end
  @cert_store_items << file
end