RUBY-1794 Verify that driver can connect to server with full TLS verification (#1380)

* RUBY-1794 documentation for running tests with TLS verification

* RUBY-1794 refactor TLS option handling

Author: p-mongo

lib/mongo/server/connectable.rb

@@ -23,15 +23,15 @@ module Connectable
       # The ssl option prefix.
       #
       # @since 2.1.0
+      # @deprecated
       SSL = 'ssl'.freeze
 
       # The default time in seconds to timeout an operation executed on a socket.
       #
       # @since 2.0.0
       #
-      # @deprecated Timeouts on Ruby sockets aren't effective so this default option is
-      #   no longer used.
-      #   Will be removed in driver version 3.0.
+      # @deprecated Timeouts on Ruby sockets aren't effective so this default
+      #   option is no longer used. Will be removed in driver version 3.0.
       TIMEOUT = 5.freeze
 
       # @return [ Integer ] pid The process id when the connection was created.
@@ -69,7 +69,11 @@ def connected?
       private
 
       def ssl_options
-        @ssl_options[:ssl] == true ? @ssl_options : {}
+        @ssl_options ||= if options[:ssl]
+          options.select { |k, v| k.to_s.start_with?('ssl') }
+        else
+          {}
+        end.freeze
       end
 
       def ensure_connected

lib/mongo/server/connection.rb

@@ -93,7 +93,6 @@ def initialize(server, options = {})
         @monitoring = server.monitoring
         @options = options.freeze
         @server = server
-        @ssl_options = options.select { |k, v| k.to_s.start_with?(SSL) }.freeze
         @socket = nil
         @last_checkin = nil
         @auth_mechanism = nil

lib/mongo/server/monitor/connection.rb

@@ -114,7 +114,6 @@ def initialize(address, options = {})
           @address = address
           @options = options.freeze
           @app_metadata = options[:app_metadata]
-          @ssl_options = options.reject { |k, v| !k.to_s.start_with?(SSL) }
           @socket = nil
           @pid = Process.pid
           @compressor = nil

lib/mongo/socket/ssl.rb

@@ -149,10 +149,16 @@ def create_context(options)
       end
 
       def set_cert(context, options)
+        # Since we clear cert_text during processing, we need to examine
+        # ssl_cert_object here to avoid considering it if we have also
+        # processed the text.
         if options[:ssl_cert]
           cert_text = File.read(options[:ssl_cert])
+          cert_object = nil
+        elsif cert_text = options[:ssl_cert_string]
+          cert_object = nil
         else
-          cert_text = options[:ssl_cert_string]
+          cert_object = options[:ssl_cert_object]
         end
 
         # The client certificate may be a single certificate or a bundle
@@ -185,8 +191,8 @@ def set_cert(context, options)
 
         if cert_text
           context.cert = OpenSSL::X509::Certificate.new(cert_text)
-        elsif options[:ssl_cert_object]
-          context.cert = options[:ssl_cert_object]
+        elsif cert_object
+          context.cert = cert_object
         end
       end
 

spec/README.md

@@ -87,14 +87,40 @@ cluster topology.
 ## TLS With Verification
 
 The test suite includes a set of TLS certificates for configuring a server
-and a client to perform full TLS verification. The server can be started as
-follows, if the current directory is the top of the driver source tree:
+and a client to perform full TLS verification in the `spec/support/certificates`
+directory. The server can be started as follows, if the current directory is
+the top of the driver source tree:
 
     mlaunch init --single --dir /tmp/mdb-ssl --sslMode requireSSL \
       --sslPEMKeyFile `pwd`/spec/support/certificates/server.pem \
       --sslCAFile `pwd`/spec/support/certificates/ca.pem \
       --sslClientCertificate `pwd`/spec/support/certificates/client.pem
 
+To test that the driver works when the server's certificate is signed by an
+intermediate certificate (i.e. uses certificate chaining), use the chained
+server certificate bundle:
+
+    mlaunch init --single --dir /tmp/mdb-ssl --sslMode requireSSL \
+      --sslPEMKeyFile `pwd`/spec/support/certificates/server-second-level-bundle.pem \
+      --sslCAFile `pwd`/spec/support/certificates/ca.pem \
+      --sslClientCertificate `pwd`/spec/support/certificates/client.pem
+
+The driver's test suite is configured to verify certificates by default.
+If the server is launched with the certificates from the driver's test suite,
+the test suite can be run simply by specifying `tls=true` URI option:
+
+    MONGODB_URI='mongodb://localhost:27017/?tls=true' rake 
+
+The driver's test suite can also be executed against a server launched with
+any other certificates. In this case the certificates need to be explicitly
+specified in the URI, for example as follows:
+
+    MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsCAFile=path/to/ca.crt&tlsCertificateKeyFile=path/to/client.pem' rake 
+
+Note that some tests (specifically testing TLS verification) expect the server
+to be launched using the certificates in the driver's test suite, and will
+fail when run against a server using other certificates.
+
 ## TLS Without Verification
 
 It is also possible to enable TLS but omit certificate verification. In this
@@ -111,6 +137,9 @@ verification, run:
 
     MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsInsecure=true' rake 
 
+Note that there are tests in the test suite that cover TLS verification, and
+they may fail if the test suite is run in this way.
+
 ## Authentication
 
 mlaunch can configure authentication on the server: