class HTTPClient::SSLConfig

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

Trust Anchor Control

SSLConfig loads 'httpclient/cacert.p7s' 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.p7s' is created by the author and included in released package.

‘cacert.p7s’ is automatically generated from JDK 1.6.

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

Constants

DIST_CERT
DIST_CERT_SHA1

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=.

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 authenticateion.

nil by default. (no client authenticateion)

client_key[R]
OpenSSL::PKey::PKey

private key for SSL client authentication.

nil by default. (no client authenticateion)

options[R]

A number of OpenSSL’s SSL options. Default value is OpenSSL::SSL::OP_ALL | OpenSSL::SSL::OP_NO_SSLv2

ssl_version[R]

String name of OpenSSL's SSL version method name: SSLv2, SSLv23 or SSLv3

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.

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 75
def initialize(client)
  return unless SSLEnabled
  @client = client
  @cert_store = X509::Store.new
  @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 = "SSLv3"
  @options = defined?(SSL::OP_ALL) ? SSL::OP_ALL | SSL::OP_NO_SSLv2 : nil
  # OpenSSL 0.9.8 default: "ALL:!ADH:!LOW:!EXP:!MD5:+SSLv2:@STRENGTH"
  @ciphers = "ALL:!aNULL:!eNULL:!SSLv2" # OpenSSL >1.0.0 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.

Calling this method resets all existing sessions.

# File lib/httpclient/ssl_config.rb, line 203
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.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 176
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)
  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 183
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 163
def cert_store=(cert_store)
  @cacerts_loaded = true # avoid lazy override
  @cert_store = cert_store
  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 259
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 153
def clear_cert_store
  @cacerts_loaded = true # avoid lazy override
  @cert_store = X509::Store.new
  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 104
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 113
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 318
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}")
  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 193
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 251
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 338
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'
      %rCA:(TRUE|FALSE), pathlen:(\d+)/ =~ ex.value
      ca = ($1 == 'TRUE')
      pathlen = $2.to_i
    when 'keyUsage'
      usage = ex.value.split(%r\s*,\s*/)
      ca = usage.include?('Certificate Sign')
      server_auth = usage.include?('Key Encipherment')
    when 'extendedKeyUsage'
      usage = ex.value.split(%r\s*,\s*/)
      server_auth = usage.include?('Netscape Server Gated Crypto')
    when 'nsCertType'
      usage = ex.value.split(%r\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) 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 125
def set_client_cert_file(cert_file, key_file)
  @client_cert = X509::Certificate.new(File.open(cert_file) { |f| f.read })
  @client_key = PKey::RSA.new(File.open(key_file) { |f| f.read })
  change_notify
end
set_crl(crl) click to toggle source
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 142
def set_default_paths
  @cacerts_loaded = true # avoid lazy override
  @cert_store = X509::Store.new
  @cert_store.set_default_paths
  change_notify
end
set_trust_ca(trust_ca_file_or_hashed_dir) click to toggle source
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 94
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 242
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 234
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 225
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 217
def verify_mode=(verify_mode)
  @verify_mode = verify_mode
  change_notify
end