Represents SSL configuration for HTTPClient instance. The implementation depends on OpenSSL.
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. Regardless its filename extension (p7s), HTTPClient doesn't verify the signature in it.
You may want to change trust anchor by yourself. Call #clear_cert_store then #add_trust_ca for that purpose.
OpenSSL::X509::X509::Store used for verification. You can reset the store with #clear_cert_store and set the new store with #cert_store=.
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.
certificate for SSL client authenticateion.
nil by default. (no client authenticateion)
private key for SSL client authentication.
nil by default. (no client authenticateion)
A number of OpenSSL's SSL options. Default value is OpenSSL::SSL::OP_ALL | OpenSSL::SSL::OP_NO_SSLv2
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.
A number which represents OpenSSL's verify mode. Default value is OpenSSL::SSL::VERIFY_PEER | OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT.
Creates a SSLConfig.
# File lib/httpclient/ssl_config.rb, line 82 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 = :auto @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
Adds CRL for verification.
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 210 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
Sets trust anchor certificate(s) for verification.
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 183 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
# File lib/httpclient/ssl_config.rb, line 190 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 170 def cert_store=(cert_store) @cacerts_loaded = true # avoid lazy override @cert_store = cert_store 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 266 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 160 def clear_cert_store @cacerts_loaded = true # avoid lazy override @cert_store = X509::Store.new 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 111 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 120 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 325 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
Loads default trust anchors. Calling this method resets all existing sessions.
# File lib/httpclient/ssl_config.rb, line 200 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 258 def options=(options) @options = options change_notify end
Sample callback method: CAUTION: does not check CRL/ARL.
# File lib/httpclient/ssl_config.rb, line 345 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.
must be a filename of PEM/DER formatted 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 132 def set_client_cert_file(cert_file, key_file, pass = nil) @client_cert = X509::Certificate.new(File.open(cert_file) { |f| f.read }) @client_key = PKey::RSA.new(File.open(key_file) { |f| f.read }, 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 149 def set_default_paths @cacerts_loaded = true # avoid lazy override @cert_store = X509::Store.new @cert_store.set_default_paths 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 101 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 249 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 241 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 232 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 224 def verify_mode=(verify_mode) @verify_mode = verify_mode change_notify end
# File lib/httpclient/ssl_config.rb, line 398 def change_notify @client.reset_all nil end
# File lib/httpclient/ssl_config.rb, line 403 def load_cacerts(cert_store) file = File.join(File.dirname(__FILE__), 'cacert.p7s') add_trust_ca_to_store(cert_store, file) end