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
OpenSSL::X509::X509::Store used for verification. You can reset the store with #clear_cert_store and set the new store with #cert_store=.
These array keeps original files/dirs that was added to @cert_store
- OpenSSL::X509::Certificate
-
certificate for SSL client authentication.
nil by default. (no client authentication)
- OpenSSL::PKey::PKey
-
private key for SSL client authentication.
nil by default. (no client authentication)
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.
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.
SSL timeout in sec. nil by default.
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.
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.
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
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
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
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
# 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
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
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
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
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
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 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
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
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 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
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
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
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
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
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
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
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
# File lib/httpclient/ssl_config.rb, line 436 def change_notify @client.reset_all nil end
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