🔒 Add ssl_ctx and ssl_ctx_params attr readers

`Net::IMAP#ssl_ctx` will return the `OpenSSL::SSL::SSLContext`
used by the `OpenSSL::SSL::SSLSocket` when TLS is attempted, even when
the TLS handshake is unsuccessful.  The context object will be frozen.
It will return `nil` for a plaintext connection.

`Net::IMAP#ssl_ctx_params` will return the parameters that were sent to
`OpenSSL::SSL::SSLContext#set_params` when the connection tries to use
TLS (even when unsuccessful).  It will return `false` for a plaintext
connection.

Additionally, error handling for the arguments to `#starttls` was moved
*before* sending the command to the server.  This way a simple argument
error will still raise an exception, but won't result in dropping the
connection.  Because `ssl_ctx` is also created ahead of time, this will
also catch invalid SSLContext params.

Author: nevans

lib/net/imap.rb

@@ -722,6 +722,21 @@ class << self
     # The port this client connected to
     attr_reader :port
 
+    # Returns the
+    # {SSLContext}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html]
+    # used by the SSLSocket when TLS is attempted, even when the TLS handshake
+    # is unsuccessful.  The context object will be frozen.
+    #
+    # Returns +nil+ for a plaintext connection.
+    attr_reader :ssl_ctx
+
+    # Returns the parameters that were sent to #ssl_ctx
+    # {set_params}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-set_params]
+    # when the connection tries to use TLS (even when unsuccessful).
+    #
+    # Returns +false+ for a plaintext connection.
+    attr_reader :ssl_ctx_params
+
     # Creates a new Net::IMAP object and connects it to the specified
     # +host+.
     #
@@ -804,7 +819,7 @@ def initialize(host, options = {}, *deprecated)
       @port = options[:port] || (options[:ssl] ? SSL_PORT : PORT)
       @open_timeout = options[:open_timeout] || 30
       @idle_response_timeout = options[:idle_response_timeout] || 5
-      ssl_ctx_params = options[:ssl]
+      @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options[:ssl])
 
       # Basic Client State
       @utf8_strings = false
@@ -835,7 +850,8 @@ def initialize(host, options = {}, *deprecated)
       # Connection
       @tls_verified = false
       @sock = tcp_socket(@host, @port)
-      start_imap_connection(ssl_ctx_params)
+      start_tls_session if ssl_ctx
+      start_imap_connection
 
       # DEPRECATED: to remove in next version
       @client_thread = Thread.current
@@ -1083,17 +1099,18 @@ def logout
     # Cached #capabilities will be cleared when this method completes.
     #
     def starttls(options = {}, verify = true)
+      begin
+        # for backward compatibility
+        certs = options.to_str
+        options = create_ssl_params(certs, verify)
+      rescue NoMethodError
+      end
+      @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options || {})
       send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
-          begin
-            # for backward compatibility
-            certs = options.to_str
-            options = create_ssl_params(certs, verify)
-          rescue NoMethodError
-          end
           clear_cached_capabilities
           clear_responses
-          start_tls_session(options)
+          start_tls_session
         end
       end
     end
@@ -2351,8 +2368,7 @@ def convert_deprecated_options(
       options
     end
 
-    def start_imap_connection(ssl_ctx_params)
-      start_tls_session(ssl_ctx_params) if ssl_ctx_params
+    def start_imap_connection
       @greeting        = get_server_greeting
       @capabilities    = capabilities_from_resp_code @greeting
       @receiver_thread = start_receiver_thread
@@ -2664,6 +2680,21 @@ def normalize_searching_criteria(keys)
       end
     end
 
+    def build_ssl_ctx(ssl)
+      if ssl
+        params = (Hash.try_convert(ssl) || {}).freeze
+        context = SSLContext.new
+        context.set_params(params)
+        if defined?(VerifyCallbackProc)
+          context.verify_callback = VerifyCallbackProc
+        end
+        context.freeze
+        [params, context]
+      else
+        false
+      end
+    end
+
     def create_ssl_params(certs = nil, verify = true)
       params = {}
       if certs
@@ -2681,28 +2712,15 @@ def create_ssl_params(certs = nil, verify = true)
       return params
     end
 
-    def start_tls_session(params = {})
-      unless defined?(OpenSSL::SSL)
-        raise "SSL extension not installed"
-      end
-      if @sock.kind_of?(OpenSSL::SSL::SSLSocket)
-        raise RuntimeError, "already using SSL"
-      end
-      begin
-        params = params.to_hash
-      rescue NoMethodError
-        params = {}
-      end
-      context = SSLContext.new
-      context.set_params(params)
-      if defined?(VerifyCallbackProc)
-        context.verify_callback = VerifyCallbackProc
-      end
-      @sock = SSLSocket.new(@sock, context)
+    def start_tls_session
+      raise "SSL extension not installed" unless defined?(OpenSSL::SSL)
+      raise "already using SSL" if @sock.kind_of?(OpenSSL::SSL::SSLSocket)
+      raise "cannot start TLS without SSLContext" unless ssl_ctx
+      @sock = SSLSocket.new(@sock, ssl_ctx)
       @sock.sync_close = true
       @sock.hostname = @host if @sock.respond_to? :hostname=
       ssl_socket_connect(@sock, @open_timeout)
-      if context.verify_mode != VERIFY_NONE
+      if ssl_ctx.verify_mode != VERIFY_NONE
         @sock.post_connection_check(@host)
         @tls_verified = true
       end

test/net/imap/test_imap.rb

@@ -57,6 +57,10 @@ def test_imaps_with_ca_file
       end
       assert_equal true, verified
       assert_equal true, imap.tls_verified?
+      assert_equal({ca_file: CA_FILE}, imap.ssl_ctx_params)
+      assert_equal(CA_FILE, imap.ssl_ctx.ca_file)
+      assert_equal(OpenSSL::SSL::VERIFY_PEER, imap.ssl_ctx.verify_mode)
+      assert imap.ssl_ctx.verify_hostname
     end
 
     def test_imaps_verify_none
@@ -76,6 +80,10 @@ def test_imaps_verify_none
       end
       assert_equal false, verified
       assert_equal false, imap.tls_verified?
+      assert_equal({verify_mode: OpenSSL::SSL::VERIFY_NONE},
+                   imap.ssl_ctx_params)
+      assert_equal(nil, imap.ssl_ctx.ca_file)
+      assert_equal(OpenSSL::SSL::VERIFY_NONE, imap.ssl_ctx.verify_mode)
     end
 
     def test_imaps_post_connection_check
@@ -92,16 +100,41 @@ def test_imaps_post_connection_check
   end
 
   if defined?(OpenSSL::SSL)
+    def test_starttls_unknown_ca
+      imap = nil
+      assert_raise(OpenSSL::SSL::SSLError) do
+        ex = nil
+        starttls_test do |port|
+          imap = Net::IMAP.new("localhost", port: port)
+          imap.starttls
+          imap
+        rescue => ex
+          imap
+        end
+        raise ex if ex
+      end
+      assert_equal false, imap.tls_verified?
+      assert_equal({}, imap.ssl_ctx_params)
+      assert_equal(nil, imap.ssl_ctx.ca_file)
+      assert_equal(OpenSSL::SSL::VERIFY_PEER, imap.ssl_ctx.verify_mode)
+    end
+
     def test_starttls
-      verified, imap = :unknown, nil
+      initial_verified, initial_ctx, initial_params = :unknown, :unknown, :unknown
+      imap = nil
       starttls_test do |port|
         imap = Net::IMAP.new("localhost", :port => port)
+        initial_verified = imap.tls_verified?
+        initial_params   = imap.ssl_ctx_params
+        initial_ctx      = imap.ssl_ctx
         imap.starttls(:ca_file => CA_FILE)
-        verified = imap.tls_verified?
         imap
       end
-      assert_equal true, verified
+      assert_equal false, initial_verified
+      assert_equal false, initial_params
+      assert_equal nil,   initial_ctx
       assert_equal true, imap.tls_verified?
+      assert_equal({ca_file: CA_FILE}, imap.ssl_ctx_params)
     rescue SystemCallError
       skip $!
     ensure
@@ -111,17 +144,18 @@ def test_starttls
     end
 
     def test_starttls_stripping
-      verified, imap = :unknown, nil
+      imap = nil
       starttls_stripping_test do |port|
         imap = Net::IMAP.new("localhost", :port => port)
         assert_raise(Net::IMAP::UnknownResponseError) do
           imap.starttls(:ca_file => CA_FILE)
         end
-        verified = imap.tls_verified?
         imap
       end
-      assert_equal false, verified
       assert_equal false, imap.tls_verified?
+      assert_equal({ca_file: CA_FILE},        imap.ssl_ctx_params)
+      assert_equal(CA_FILE,                   imap.ssl_ctx.ca_file)
+      assert_equal(OpenSSL::SSL::VERIFY_PEER, imap.ssl_ctx.verify_mode)
     end
   end
 
@@ -1123,6 +1157,7 @@ def starttls_test
         sock.gets
         sock.print("* BYE terminating connection\r\n")
         sock.print("RUBY0002 OK LOGOUT completed\r\n")
+      rescue OpenSSL::SSL::SSLError
       ensure
         sock.close
         server.close