From 36bd4052be0ff07742c5d8bca68b58c9ce69628c Mon Sep 17 00:00:00 2001 From: "Yamashita, Yuu" Date: Fri, 30 Oct 2026 11:25:46 +0900 Subject: [PATCH 1/4] Use OpenSSL trust store by default (#480) --- lib/httpclient/ssl_config.rb | 14 ++++++++++-- test/test_ssl.rb | 4 ++++ test/test_ssl_config.rb | 43 ++++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 2 deletions(-) diff --git a/lib/httpclient/ssl_config.rb b/lib/httpclient/ssl_config.rb index 29944427..5b206b4d 100644 --- a/lib/httpclient/ssl_config.rb +++ b/lib/httpclient/ssl_config.rb @@ -116,6 +116,7 @@ def attr_config(symbol) CIPHERS_DEFAULT = "ALL:!aNULL:!eNULL:!SSLv2" # OpenSSL >1.0.0 default + BUNDLED_CACERT_FILE = File.join(File.dirname(__FILE__), 'cacert.pem').freeze # Public keys whose SPKI SHA-256 hashes are listed below are considered blocked. # The list covers eight eMudhra intermediate CA public keys whose corresponding @@ -200,6 +201,7 @@ def self.blocked_public_key?(public_key_der) # OpenSSL::X509::X509::Store used for verification. You can reset the # store with clear_cert_store and set the new store with cert_store=. attr_reader :cert_store # don't use if you don't know what it is. + attr_reader :cacert_file # For server side configuration. Ignore this. attr_config :client_ca # :nodoc: @@ -214,6 +216,7 @@ def cert_store_items; @cert_store._httpclient_cert_store_items; end def initialize(client) return unless SSLEnabled @client = client + @cacert_file = X509::DEFAULT_CERT_FILE @cert_store = X509::Store.new @cert_store_crl_items = [] @client_cert = @client_key = @client_key_pass = @client_ca = nil @@ -309,6 +312,14 @@ def add_trust_ca(trust_ca_file_or_hashed_dir) end alias set_trust_ca add_trust_ca + def cacert_file=(file) + store = X509::Store.new + store._httpclient_cert_store_items.clear if defined?(JRUBY_VERSION) + add_trust_ca_to_store(store, file) + @cacert_file = file + self.cert_store = store + end + 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) @@ -523,8 +534,7 @@ def change_notify # Use 2048 bit certs trust anchor def load_cacerts(cert_store) - file = File.join(File.dirname(__FILE__), 'cacert.pem') - add_trust_ca_to_store(cert_store, file) + add_trust_ca_to_store(cert_store, @cacert_file) end end diff --git a/test/test_ssl.rb b/test/test_ssl.rb index 35cd23d2..71af804c 100644 --- a/test/test_ssl.rb +++ b/test/test_ssl.rb @@ -106,6 +106,8 @@ def test_blocked_peer_certificate_before_request def test_blocked_intermediate_with_default_paths escape_env do + # Nix's OpenSSL can prioritize this CA bundle path over SSL_CERT_FILE. + ENV.delete('NIX_SSL_CERT_FILE') ENV['SSL_CERT_FILE'] = path('ca-chain.pem') @client.ssl_config.set_default_paths @server.ssl_context.extra_chain_cert = [cert('subca.cert')] @@ -370,6 +372,8 @@ def test_set_default_paths @client.get(@url) end escape_env do + # Nix's OpenSSL can prioritize this CA bundle path over SSL_CERT_FILE. + ENV.delete('NIX_SSL_CERT_FILE') ENV['SSL_CERT_FILE'] = File.join(DIR, 'ca-chain.pem') @client.ssl_config.set_default_paths @client.get(@url) diff --git a/test/test_ssl_config.rb b/test/test_ssl_config.rb index 67b82d2c..94621b88 100644 --- a/test/test_ssl_config.rb +++ b/test/test_ssl_config.rb @@ -49,3 +49,46 @@ def test_blocked_cross_signed_keys_without_der_export end end end + +# JRuby uses its JVM trust manager instead of SSLConfig#set_context. +unless defined?(JRUBY_VERSION) + class TestOpenSSLTrustStore < Test::Unit::TestCase + def setup + @client = HTTPClient.new + @config = @client.ssl_config + @loaded_files = [] + loaded_files = @loaded_files + @config.define_singleton_method(:add_trust_ca_to_store) do |_store, file| + loaded_files << file + end + end + + def teardown + @client.reset_all if @client + end + + def test_default_cert_file_is_loaded_once + configure_context + configure_context + assert_equal([OpenSSL::X509::DEFAULT_CERT_FILE], @loaded_files) + end + + def test_bundled_ca_can_be_selected_with_cacert_file + @config.cacert_file = bundled_ca_file + configure_context + assert_equal([bundled_ca_file], @loaded_files) + end + + private + + def configure_context + context = OpenSSL::SSL::SSLContext.new + @config.set_context(context) + assert_same(@config.cert_store, context.cert_store) + end + + def bundled_ca_file + HTTPClient::SSLConfig::BUNDLED_CACERT_FILE + end + end +end From 57ba09535d8debe8fa653fd24f7b49888a8e6925 Mon Sep 17 00:00:00 2001 From: "Yamashita, Yuu" Date: Fri, 30 Oct 2026 11:31:34 +0900 Subject: [PATCH 2/4] Document OpenSSL trust store defaults (#480) --- CHANGELOG.md | 2 ++ README.md | 28 +++++++++++++++++++----- lib/httpclient/ssl_config.rb | 41 +++++++++++++++++++----------------- 3 files changed, 47 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c44a50c..503b3404 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ * Refresh the bundled Mozilla CA certificates to the October 20, 2026 snapshot, building on [#444](https://github.com/nahi/httpclient/pull/444). +* Use `OpenSSL::X509::DEFAULT_CERT_FILE` by default on MRI. `SSLConfig#cacert_file=` can select another CA file, including the bundled certificates via `SSLConfig::BUNDLED_CACERT_FILE` ([#480](https://github.com/nahi/httpclient/issues/480)). + * With peer verification enabled and no custom verification callback, reject TLS connections when a server supplies certificates containing blocked eMudhra intermediate CA public keys, including cross-signed variants ([#480](https://github.com/nahi/httpclient/issues/480)). Connections are also rejected when a server supplies an unused certificate containing a blocked public key. `VERIFY_NONE`/`nil` disables this check; a custom verification callback replaces the default policy and is responsible for certificate validation. diff --git a/README.md b/README.md index 80e695b6..0f15f5d6 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,25 @@ You can install httpclient via rubygems: `gem install httpclient` See [HTTPClient](http://www.rubydoc.info/gems/httpclient/frames) for documentation. You can also check sample/howto.rb how to use APIs. +### TLS trust store + +On MRI, HTTPClient uses `OpenSSL::X509::DEFAULT_CERT_FILE` by default. To +preserve compatibility with previous releases' default CA selection, select the +bundled Mozilla CA certificates explicitly: + +```ruby +client = HTTPClient.new +client.ssl_config.cacert_file = HTTPClient::SSLConfig::BUNDLED_CACERT_FILE +``` + +Assigning `cacert_file` loads that file into a new certificate store, replacing +the current store and resetting existing sessions. You can assign it after a +connection has been made. `load_trust_ca` adds the selected file to the current +store and resets existing sessions. On JRuby, the default trust store remains +the JVM's; assigning `cacert_file` explicitly selects a certificate file. Use +`client.ssl_config.set_default_paths` on MRI to load OpenSSL's configured +default certificate file and directory. + ### TLS certificate restrictions Blocked public keys are identified by their SPKI SHA-256 hashes in @@ -91,11 +110,10 @@ context. With peer verification enabled, its return value controls certificate verification. The caller is responsible for the custom callback's validation policy. Hostname verification is unchanged. -Note: MRI uses HTTPClient's bundled `cacert.pem` by default, while JRuby uses -the JVM's CA certificates and certificate validation. Secure operation on JRuby -depends on keeping the JVM and its CA certificates up to date. HTTPClient's -additional check may not detect blocked intermediates found only in a local -trust store or obtained through JVM issuer retrieval (such as AIA when enabled). +On JRuby, HTTPClient uses the JVM's CA certificates and validation by default. +Keep the JVM and its CA certificates up to date. The additional blocked-key +check may not detect intermediates found only in a local trust store or obtained +through JVM issuer retrieval (such as AIA when enabled). Remove unused certificates containing blocked public keys from the server's certificate chain configuration. If a certificate containing a blocked public key diff --git a/lib/httpclient/ssl_config.rb b/lib/httpclient/ssl_config.rb index 5b206b4d..829b772d 100644 --- a/lib/httpclient/ssl_config.rb +++ b/lib/httpclient/ssl_config.rb @@ -20,23 +20,20 @@ class HTTPClient # # == 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 MRI, HTTPClient uses OpenSSL::X509::DEFAULT_CERT_FILE by default. To + # preserve compatibility with previous releases' default CA selection, + # explicitly select the bundled Mozilla CA certificates: # - # On JRuby, HTTPClient uses Java runtime's trusted CA certificates, not - # cacert.pem by default. You can load cacert.pem by calling - # SSLConfig#load_trust_ca manually like: + # client = HTTPClient.new + # client.ssl_config.cacert_file = HTTPClient::SSLConfig::BUNDLED_CACERT_FILE # - # HTTPClient.new { self.ssl_config.load_trust_ca }.get("https://...") + # Assigning cacert_file loads the selected file into a new certificate store, + # replacing the current store and resetting existing sessions. It can be + # changed after connections have been made. load_trust_ca loads the selected + # file into the current store, adding to its existing certificates. # - # Secure operation on JRuby depends on keeping the JVM and its CA certificates - # up to date. - # - # You may want to change trust anchor by yourself. Call clear_cert_store - # then add_trust_ca for that purpose. + # On JRuby, HTTPClient uses the JVM's trusted CA certificates by default. + # Assign cacert_file explicitly to use a certificate file instead. # # == TLS certificate restrictions # @@ -116,6 +113,7 @@ def attr_config(symbol) CIPHERS_DEFAULT = "ALL:!aNULL:!eNULL:!SSLv2" # OpenSSL >1.0.0 default + # Bundled Mozilla CA certificates, available for explicit selection. BUNDLED_CACERT_FILE = File.join(File.dirname(__FILE__), 'cacert.pem').freeze # Public keys whose SPKI SHA-256 hashes are listed below are considered blocked. @@ -198,9 +196,11 @@ def self.blocked_public_key?(public_key_der) # See ciphers(1) man in OpenSSL for more detail. attr_config :ciphers - # OpenSSL::X509::X509::Store used for verification. You can reset the - # store with clear_cert_store and set the new store with cert_store=. + # OpenSSL::X509::Store used for verification. You can reset the store with + # clear_cert_store and set the new store with cert_store=. attr_reader :cert_store # don't use if you don't know what it is. + # Selected CA certificate file. Defaults to OpenSSL::X509::DEFAULT_CERT_FILE + # on MRI. attr_reader :cacert_file # For server side configuration. Ignore this. @@ -312,6 +312,9 @@ def add_trust_ca(trust_ca_file_or_hashed_dir) end alias set_trust_ca add_trust_ca + # Selects a CA certificate file. Replaces the current certificate store + # with a new store loaded from file and resets existing sessions. If loading + # fails, the current store and selected file are unchanged. def cacert_file=(file) store = X509::Store.new store._httpclient_cert_store_items.clear if defined?(JRUBY_VERSION) @@ -328,8 +331,9 @@ def add_trust_ca_to_store(cert_store, trust_ca_file_or_hashed_dir) end end - # Loads default trust anchors. - # Calling this method resets all existing sessions. + # Loads the selected cacert_file into the current certificate store. + # Existing certificates in the store are kept. Calling this method resets + # all existing sessions. def load_trust_ca load_cacerts(@cert_store) change_notify @@ -532,7 +536,6 @@ def change_notify nil end - # Use 2048 bit certs trust anchor def load_cacerts(cert_store) add_trust_ca_to_store(cert_store, @cacert_file) end From 7062fd252c7db0c66b76ba8662043864dbdb52bb Mon Sep 17 00:00:00 2001 From: "Yamashita, Yuu" Date: Mon, 2 Nov 2026 12:02:50 +0900 Subject: [PATCH 3/4] Preserve JRuby default CA selection --- README.md | 7 +++--- lib/httpclient/ssl_config.rb | 13 +++++------ test/test_ssl_config.rb | 42 ++++++++++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0f15f5d6..60d7989c 100644 --- a/README.md +++ b/README.md @@ -85,9 +85,10 @@ client.ssl_config.cacert_file = HTTPClient::SSLConfig::BUNDLED_CACERT_FILE Assigning `cacert_file` loads that file into a new certificate store, replacing the current store and resetting existing sessions. You can assign it after a -connection has been made. `load_trust_ca` adds the selected file to the current -store and resets existing sessions. On JRuby, the default trust store remains -the JVM's; assigning `cacert_file` explicitly selects a certificate file. Use +connection has been made. `load_trust_ca` adds the selected file, if any, to the +current store and resets existing sessions. On JRuby, CA selection defaults to +the JVM trust store and can be overridden with `SSL_CERT_FILE`; assigning +`cacert_file` explicitly selects a certificate file. Use `client.ssl_config.set_default_paths` on MRI to load OpenSSL's configured default certificate file and directory. diff --git a/lib/httpclient/ssl_config.rb b/lib/httpclient/ssl_config.rb index 829b772d..5fd55895 100644 --- a/lib/httpclient/ssl_config.rb +++ b/lib/httpclient/ssl_config.rb @@ -30,10 +30,10 @@ class HTTPClient # Assigning cacert_file loads the selected file into a new certificate store, # replacing the current store and resetting existing sessions. It can be # changed after connections have been made. load_trust_ca loads the selected - # file into the current store, adding to its existing certificates. + # file, if any, into the current store, adding to its existing certificates. # - # On JRuby, HTTPClient uses the JVM's trusted CA certificates by default. - # Assign cacert_file explicitly to use a certificate file instead. + # On JRuby, CA selection defaults to the JVM's trust store and can be + # overridden with SSL_CERT_FILE. Assign cacert_file to select a file directly. # # == TLS certificate restrictions # @@ -200,7 +200,7 @@ def self.blocked_public_key?(public_key_der) # clear_cert_store and set the new store with cert_store=. attr_reader :cert_store # don't use if you don't know what it is. # Selected CA certificate file. Defaults to OpenSSL::X509::DEFAULT_CERT_FILE - # on MRI. + # on MRI and nil on JRuby, where CA selection is left to the runtime. attr_reader :cacert_file # For server side configuration. Ignore this. @@ -216,7 +216,8 @@ def cert_store_items; @cert_store._httpclient_cert_store_items; end def initialize(client) return unless SSLEnabled @client = client - @cacert_file = X509::DEFAULT_CERT_FILE + # nil leaves JRuby's default CA selection (JVM store or SSL_CERT_FILE) intact. + @cacert_file = defined?(JRUBY_VERSION) ? nil : X509::DEFAULT_CERT_FILE @cert_store = X509::Store.new @cert_store_crl_items = [] @client_cert = @client_key = @client_key_pass = @client_ca = nil @@ -537,7 +538,7 @@ def change_notify end def load_cacerts(cert_store) - add_trust_ca_to_store(cert_store, @cacert_file) + add_trust_ca_to_store(cert_store, @cacert_file) unless @cacert_file.nil? end end diff --git a/test/test_ssl_config.rb b/test/test_ssl_config.rb index 94621b88..c013f5ab 100644 --- a/test/test_ssl_config.rb +++ b/test/test_ssl_config.rb @@ -50,6 +50,48 @@ def test_blocked_cross_signed_keys_without_der_export end end +class TestCACertFile < Test::Unit::TestCase + def setup + @client = HTTPClient.new + @config = @client.ssl_config + @ca_file = File.join(__dir__, 'ca.cert') + end + + def teardown + @client.reset_all + end + + if defined?(JRUBY_VERSION) + def test_load_trust_ca_keeps_default_selection_when_no_file_is_selected + default_items = @config.cert_store_items.dup + @config.load_trust_ca + + assert_nil(@config.cacert_file) + assert_equal(default_items, @config.cert_store_items) + end + end + + def test_cacert_file_replaces_store + @config.add_trust_ca(File.join(__dir__, 'ca-chain.pem')) + original_store = @config.cert_store + @config.cacert_file = @ca_file + + assert_not_same(original_store, @config.cert_store) + assert_equal(@ca_file, @config.cacert_file) + assert_equal([@ca_file], @config.cert_store_items) if defined?(JRUBY_VERSION) + end + + def test_load_trust_ca_uses_selected_file + @config.cacert_file = @ca_file + @config.clear_cert_store + @config.load_trust_ca + + certificate = OpenSSL::X509::Certificate.new(File.read(@ca_file)) + @config.cert_store.time = certificate.not_before + 1 + assert(@config.cert_store.verify(certificate), @config.cert_store.error_string) + end +end + # JRuby uses its JVM trust manager instead of SSLConfig#set_context. unless defined?(JRUBY_VERSION) class TestOpenSSLTrustStore < Test::Unit::TestCase From d68fd9849e72f468afc2f3a94276cc41b8c27191 Mon Sep 17 00:00:00 2001 From: "Yamashita, Yuu" Date: Mon, 16 Nov 2026 12:35:12 +0900 Subject: [PATCH 4/4] Keep bundled CA certificates as the MRI default and warn on use (#480) Until HTTPClient 3.0.0, MRI keeps using the bundled CA certificates by default. Loading them emits a deprecation notice once per process that points to OpenSSL::X509::DEFAULT_CERT_FILE as an opt-in replacement. - Add SSLConfig#cacert_file= to select a CA file. Assigning it replaces the certificate store and resets sessions. If loading fails, the previous file and store are kept. - Keep JRuby's runtime trust store as the default. An explicit load_trust_ca still adds the selected file, including the bundled one. - Cover the notice, file selection, and store replacement with tests. - Mark the 3.0.0 default change with TODO(3.0.0) comments. --- CHANGELOG.md | 3 +- README.md | 41 ++++++++--- lib/httpclient/ssl_config.rb | 37 ++++++---- test/test_ssl.rb | 11 +++ test/test_ssl_config.rb | 137 +++++++++++++++++++++++++++++++++-- 5 files changed, 195 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 82199cfb..08a0e5e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ ## Changes -* Use `OpenSSL::X509::DEFAULT_CERT_FILE` by default on MRI. `SSLConfig#cacert_file=` can select another CA file, including the bundled certificates via `SSLConfig::BUNDLED_CACERT_FILE` ([#480](https://github.com/nahi/httpclient/issues/480)). +* Add `SSLConfig#cacert_file=` to select a CA file, including `OpenSSL::X509::DEFAULT_CERT_FILE` for opting in to the future MRI default. The MRI default remains the bundled CA certificates until HTTPClient 3.0.0; JRuby continues to use runtime defaults ([#480](https://github.com/nahi/httpclient/issues/480)). +* Warn once per process when the bundled CA certificates (`SSLConfig::BUNDLED_CACERT_FILE`) are loaded. Starting with HTTPClient 3.0.0, MRI will use `OpenSSL::X509::DEFAULT_CERT_FILE` by default. ## Change Log diff --git a/README.md b/README.md index 60d7989c..6bb0cbc3 100644 --- a/README.md +++ b/README.md @@ -74,23 +74,40 @@ You can also check sample/howto.rb how to use APIs. ### TLS trust store -On MRI, HTTPClient uses `OpenSSL::X509::DEFAULT_CERT_FILE` by default. To -preserve compatibility with previous releases' default CA selection, select the -bundled Mozilla CA certificates explicitly: + + +Before HTTPClient 3.0.0, MRI uses the bundled Mozilla CA certificates +(`HTTPClient::SSLConfig::BUNDLED_CACERT_FILE`) by default. Loading them, +implicitly or explicitly, emits a deprecation warning once per process. Merely +creating a client does not emit the warning. + +**Starting with HTTPClient 3.0.0, MRI will use +`OpenSSL::X509::DEFAULT_CERT_FILE` by default.** To opt in and test your +application before upgrading: ```ruby client = HTTPClient.new -client.ssl_config.cacert_file = HTTPClient::SSLConfig::BUNDLED_CACERT_FILE +client.ssl_config.cacert_file = OpenSSL::X509::DEFAULT_CERT_FILE ``` -Assigning `cacert_file` loads that file into a new certificate store, replacing -the current store and resetting existing sessions. You can assign it after a -connection has been made. `load_trust_ca` adds the selected file, if any, to the -current store and resets existing sessions. On JRuby, CA selection defaults to -the JVM trust store and can be overridden with `SSL_CERT_FILE`; assigning -`cacert_file` explicitly selects a certificate file. Use -`client.ssl_config.set_default_paths` on MRI to load OpenSSL's configured -default certificate file and directory. +You can also select a custom CA file with `cacert_file=`. Assigning it loads +that file into a new certificate store, replacing the current store and +resetting existing sessions. You can assign it after a connection has been +made. If loading fails, the current store and selected file are unchanged. +`load_trust_ca` adds the selected file to the current store and resets existing +sessions. Use `client.ssl_config.set_default_paths` on MRI to load OpenSSL's +configured default certificate file and directory instead of a single file. +The trusted CA certificates can differ between the bundled file and your +OpenSSL installation; test connections to your application's HTTPS endpoints +before switching. + +On JRuby, CA selection continues to default to the JVM trust store and can be +overridden with `SSL_CERT_FILE`; the MRI default change does not apply. +Assigning `cacert_file` explicitly selects a certificate file instead of the +runtime defaults. Calling `load_trust_ca` adds the selected file (the bundled +CA certificates unless changed explicitly) to the current store, preserving +the runtime's default trust anchors unless the store was replaced or cleared. +Using the JVM defaults does not emit the bundled CA warning. ### TLS certificate restrictions diff --git a/lib/httpclient/ssl_config.rb b/lib/httpclient/ssl_config.rb index 5fd55895..affec9d8 100644 --- a/lib/httpclient/ssl_config.rb +++ b/lib/httpclient/ssl_config.rb @@ -20,20 +20,23 @@ class HTTPClient # # == Trust Anchor Control # - # On MRI, HTTPClient uses OpenSSL::X509::DEFAULT_CERT_FILE by default. To - # preserve compatibility with previous releases' default CA selection, - # explicitly select the bundled Mozilla CA certificates: + # Before HTTPClient 3.0.0, MRI uses the bundled Mozilla CA certificates + # (BUNDLED_CACERT_FILE) by default. Loading them emits a deprecation warning + # once per process. Starting with HTTPClient 3.0.0, MRI will use + # OpenSSL::X509::DEFAULT_CERT_FILE by default. To opt in now: # # client = HTTPClient.new - # client.ssl_config.cacert_file = HTTPClient::SSLConfig::BUNDLED_CACERT_FILE + # client.ssl_config.cacert_file = OpenSSL::X509::DEFAULT_CERT_FILE # # Assigning cacert_file loads the selected file into a new certificate store, # replacing the current store and resetting existing sessions. It can be # changed after connections have been made. load_trust_ca loads the selected - # file, if any, into the current store, adding to its existing certificates. + # file into the current store, adding to its existing certificates. # # On JRuby, CA selection defaults to the JVM's trust store and can be - # overridden with SSL_CERT_FILE. Assign cacert_file to select a file directly. + # overridden with SSL_CERT_FILE. Assign cacert_file to select a file directly, + # or call load_trust_ca to add the selected file (the bundled CA certificates + # unless changed explicitly) to the runtime's default trust anchors. # # == TLS certificate restrictions # @@ -113,7 +116,7 @@ def attr_config(symbol) CIPHERS_DEFAULT = "ALL:!aNULL:!eNULL:!SSLv2" # OpenSSL >1.0.0 default - # Bundled Mozilla CA certificates, available for explicit selection. + # Bundled Mozilla CA certificates, used by default on MRI before HTTPClient 3.0.0. BUNDLED_CACERT_FILE = File.join(File.dirname(__FILE__), 'cacert.pem').freeze # Public keys whose SPKI SHA-256 hashes are listed below are considered blocked. @@ -199,8 +202,8 @@ def self.blocked_public_key?(public_key_der) # OpenSSL::X509::Store used for verification. You can reset the store with # clear_cert_store and set the new store with cert_store=. attr_reader :cert_store # don't use if you don't know what it is. - # Selected CA certificate file. Defaults to OpenSSL::X509::DEFAULT_CERT_FILE - # on MRI and nil on JRuby, where CA selection is left to the runtime. + # Selected CA certificate file. Defaults to BUNDLED_CACERT_FILE. On JRuby, + # the selected file is only loaded explicitly, leaving runtime defaults intact. attr_reader :cacert_file # For server side configuration. Ignore this. @@ -216,8 +219,9 @@ def cert_store_items; @cert_store._httpclient_cert_store_items; end def initialize(client) return unless SSLEnabled @client = client - # nil leaves JRuby's default CA selection (JVM store or SSL_CERT_FILE) intact. - @cacert_file = defined?(JRUBY_VERSION) ? nil : X509::DEFAULT_CERT_FILE + # TODO(3.0.0): On MRI, the default becomes OpenSSL::X509::DEFAULT_CERT_FILE. + # When it changes, also update the notice below and every TODO(3.0.0) in the tests and README. + @cacert_file = BUNDLED_CACERT_FILE @cert_store = X509::Store.new @cert_store_crl_items = [] @client_cert = @client_key = @client_key_pass = @client_ca = nil @@ -325,11 +329,18 @@ def cacert_file=(file) end def add_trust_ca_to_store(cert_store, trust_ca_file_or_hashed_dir) - if FileTest.directory?(trust_ca_file_or_hashed_dir) + result = 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 + if File.expand_path(trust_ca_file_or_hashed_dir) == File.expand_path(BUNDLED_CACERT_FILE) + # TODO(3.0.0): Remove or rewrite this notice with the default change, and update its text. + warning('HTTPClient: the bundled CA certificates are deprecated and will be replaced ' \ + 'with OpenSSL::X509::DEFAULT_CERT_FILE as the default CA file on MRI in HTTPClient 3.0.0. ' \ + 'To switch now, use client.ssl_config.cacert_file = OpenSSL::X509::DEFAULT_CERT_FILE.') + end + result end # Loads the selected cacert_file into the current certificate store. @@ -538,7 +549,7 @@ def change_notify end def load_cacerts(cert_store) - add_trust_ca_to_store(cert_store, @cacert_file) unless @cacert_file.nil? + add_trust_ca_to_store(cert_store, @cacert_file) end end diff --git a/test/test_ssl.rb b/test/test_ssl.rb index 1f615a2f..825e4457 100644 --- a/test/test_ssl.rb +++ b/test/test_ssl.rb @@ -31,6 +31,17 @@ def read_path(filename) File.read(path(filename)) end + def test_cacert_file_replaces_store_after_connection + @client.ssl_config.cacert_file = path('ca-chain.pem') + assert_equal('hello', @client.get_content(@url)) + + @client.ssl_config.cacert_file = path('fixtures/verify.foo.cert') + assert_raise(OpenSSL::SSL::SSLError) { @client.get(@url) } + + @client.ssl_config.cacert_file = path('ca-chain.pem') + assert_equal('hello', @client.get_content(@url)) + end + def test_proxy_ssl setup_proxyserver escape_noproxy do diff --git a/test/test_ssl_config.rb b/test/test_ssl_config.rb index c013f5ab..c1d96fc5 100644 --- a/test/test_ssl_config.rb +++ b/test/test_ssl_config.rb @@ -1,5 +1,7 @@ require 'test/unit' require 'httpclient' +require 'open3' +require 'rbconfig' class TestSSLConfig < Test::Unit::TestCase # Older ruby-openssl returns generic PKey objects without DER export methods. @@ -61,13 +63,25 @@ def teardown @client.reset_all end + # TODO(3.0.0): These tests describe the 2.x MRI default. Rewrite them with the default change. + def test_bundled_ca_is_selected_by_default + assert_equal(HTTPClient::SSLConfig::BUNDLED_CACERT_FILE, @config.cacert_file) + end + if defined?(JRUBY_VERSION) - def test_load_trust_ca_keeps_default_selection_when_no_file_is_selected + def test_jruby_keeps_runtime_default_trust_store + default_items = [ENV['SSL_CERT_FILE'] || :default] + HTTPClient::JRubySSLSocket.allocate.create_ssl_context(@config) + + assert_equal(default_items, @config.cert_store_items) + end + + def test_load_trust_ca_adds_bundled_ca_to_jruby_defaults default_items = @config.cert_store_items.dup @config.load_trust_ca - assert_nil(@config.cacert_file) - assert_equal(default_items, @config.cert_store_items) + assert_equal(default_items + [HTTPClient::SSLConfig::BUNDLED_CACERT_FILE], + @config.cert_store_items) end end @@ -81,6 +95,18 @@ def test_cacert_file_replaces_store assert_equal([@ca_file], @config.cert_store_items) if defined?(JRUBY_VERSION) end + def test_cacert_file_failure_preserves_current_configuration + @config.cacert_file = @ca_file + original_store = @config.cert_store + + assert_raise(OpenSSL::X509::StoreError) do + @config.cacert_file = File.join(__dir__, 'missing-ca-file.pem') + end + + assert_same(original_store, @config.cert_store) + assert_equal(@ca_file, @config.cacert_file) + end + def test_load_trust_ca_uses_selected_file @config.cacert_file = @ca_file @config.clear_cert_store @@ -109,16 +135,18 @@ def teardown @client.reset_all if @client end - def test_default_cert_file_is_loaded_once + # TODO(3.0.0): These tests describe the 2.x MRI default. Rewrite them with the default change. + def test_bundled_ca_is_loaded_once_by_default configure_context configure_context - assert_equal([OpenSSL::X509::DEFAULT_CERT_FILE], @loaded_files) + assert_equal([bundled_ca_file], @loaded_files) end - def test_bundled_ca_can_be_selected_with_cacert_file - @config.cacert_file = bundled_ca_file + def test_openssl_default_ca_can_be_selected_with_cacert_file + @config.cacert_file = OpenSSL::X509::DEFAULT_CERT_FILE configure_context - assert_equal([bundled_ca_file], @loaded_files) + configure_context + assert_equal([OpenSSL::X509::DEFAULT_CERT_FILE], @loaded_files) end private @@ -134,3 +162,96 @@ def bundled_ca_file end end end + +# Deprecation notice for the bundled CA certificates. +# TODO(3.0.0): These tests describe the 2.x MRI default. Rewrite them with the default change. +class TestBundledCACertNotice < Test::Unit::TestCase + LIB_DIR = File.expand_path('../lib', __dir__) + NOTICE_PATTERN = /bundled CA certificates are deprecated/ + + def setup + @client = HTTPClient.new + @config = @client.ssl_config + @notices = [] + notices = @notices + # Records messages before Util#warning's once-per-process filter applies. + # The filter itself is checked in a subprocess below. + @config.define_singleton_method(:warning) { |message| notices << message } + end + + def teardown + @client.reset_all + end + + def test_selecting_bundled_ca_file_emits_notice + @config.cacert_file = HTTPClient::SSLConfig::BUNDLED_CACERT_FILE + assert_equal(1, @notices.size) + end + + def test_loading_default_trust_anchors_emits_notice + @config.load_trust_ca + assert_equal(1, @notices.size) + end + + def test_notice_names_the_3_0_0_default_change_and_opt_in + @config.load_trust_ca + message = @notices.first + assert_match(/deprecated/, message) + assert_match(/HTTPClient 3\.0\.0/, message) + assert_match(/OpenSSL::X509::DEFAULT_CERT_FILE/, message) + assert_match(/cacert_file = OpenSSL::X509::DEFAULT_CERT_FILE/, message) + end + + def test_custom_ca_file_does_not_emit_notice + @config.cacert_file = File.join(__dir__, 'ca.cert') + @config.load_trust_ca + assert_empty(@notices) + end + + if defined?(JRUBY_VERSION) + # JRuby uses the JVM trust store unless the bundled file is loaded explicitly. + def test_jruby_default_trust_store_does_not_emit_notice + HTTPClient::JRubySSLSocket.allocate.create_ssl_context(@config) + assert_empty(@notices) + end + else + def test_default_ssl_context_emits_notice + @config.set_context(OpenSSL::SSL::SSLContext.new) + assert_equal(1, @notices.size) + end + + # On JRuby, DEFAULT_CERT_FILE is a JDK keystore that OpenSSL cannot load as PEM. + def test_openssl_default_ca_file_does_not_emit_notice + omit('OpenSSL default CA file is missing') unless File.exist?(OpenSSL::X509::DEFAULT_CERT_FILE) + @config.cacert_file = OpenSSL::X509::DEFAULT_CERT_FILE + @config.load_trust_ca + assert_empty(@notices) + end + end + + # Subprocess checks: process-wide once-only output and no output on creation. + # JRuby may print its own startup warnings to stderr, so only notice lines count. + + def test_creating_client_writes_no_notice + assert_empty(notice_lines_from('HTTPClient.new.ssl_config')) + end + + def test_repeated_loads_write_notice_once + lines = notice_lines_from(<<~RUBY) + config = HTTPClient.new.ssl_config + config.load_trust_ca + config.cacert_file = HTTPClient::SSLConfig::BUNDLED_CACERT_FILE + HTTPClient.new.ssl_config.load_trust_ca + RUBY + assert_equal(1, lines.size) + end + + private + + def notice_lines_from(script) + _stdout, stderr, status = Open3.capture3(RbConfig.ruby, '-I', LIB_DIR, + '-e', "require 'httpclient'\n#{script}") + assert(status.success?, stderr) + stderr.lines.grep(NOTICE_PATTERN) + end +end