Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
## Changes

* 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

### Changes in 2.10.0
Expand Down
46 changes: 41 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,43 @@ 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

<!-- TODO(3.0.0): Update this section when the MRI default changes. -->

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 = OpenSSL::X509::DEFAULT_CERT_FILE
```

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

Blocked public keys are identified by their SPKI SHA-256 hashes in
Expand All @@ -91,11 +128,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
Expand Down
69 changes: 47 additions & 22 deletions lib/httpclient/ssl_config.rb
Original file line number Diff line number Diff line change
Expand Up @@ -20,23 +20,23 @@ 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.
# 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:
#
# 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 = OpenSSL::X509::DEFAULT_CERT_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, 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,
# 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
#
Expand Down Expand Up @@ -116,6 +116,8 @@ def attr_config(symbol)


CIPHERS_DEFAULT = "ALL:!aNULL:!eNULL:!SSLv2" # OpenSSL >1.0.0 default
# 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.
# The list covers eight eMudhra intermediate CA public keys whose corresponding
Expand Down Expand Up @@ -197,9 +199,12 @@ 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 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.
attr_config :client_ca # :nodoc:
Expand All @@ -214,6 +219,9 @@ def cert_store_items; @cert_store._httpclient_cert_store_items; end
def initialize(client)
return unless SSLEnabled
@client = client
# 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
Expand Down Expand Up @@ -309,16 +317,35 @@ 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)
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)
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 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
Expand Down Expand Up @@ -521,10 +548,8 @@ def change_notify
nil
end

# 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

Expand Down
15 changes: 15 additions & 0 deletions test/test_ssl.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -106,6 +117,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')]
Expand Down Expand Up @@ -373,6 +386,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)
Expand Down
Loading
Loading