net-ssh 7.2.3 → 8.0.4

data/lib/net/ssh/transport/session.rb

@@ -27,6 +27,10 @@ module Net
         # The standard port for the SSH protocol.
         DEFAULT_PORT = 22
 
+        # Packets held back during a re-key are bounded so a server can't exhaust memory (GHSA-ggxh-cfwq-5xqc).
+        MAX_QUEUED_PACKETS = 16_384
+        MAX_QUEUED_BYTES = 32 * 1024 * 1024
+
         # The host to connect to, as given to the constructor.
         attr_reader :host
 
@@ -62,6 +66,7 @@ module Net
           @port = options[:port] || DEFAULT_PORT
           @bind_address = options[:bind_address] || nil
           @options = options
+          @host_key_verifier = select_host_key_verifier(options[:verify_host_key])
 
           @socket =
             if (factory = options[:proxy])
@@ -75,12 +80,12 @@ module Net
 
           @socket.extend(PacketStream)
           @socket.logger = @logger
+          set_no_delay unless options[:no_delay] == false
 
           debug { "connection established" }
 
           @queue = []
-
-          @host_key_verifier = select_host_key_verifier(options[:verify_host_key])
+          @queued_bytes = 0
 
           @server_version = ServerVersion.new(socket, logger, options[:timeout])
 
@@ -88,7 +93,11 @@ module Net
           @algorithms.start
           wait { algorithms.initialized? }
         rescue Errno::ETIMEDOUT
+          @socket&.close
           raise Net::SSH::ConnectionTimeout
+        rescue StandardError
+          @socket&.close
+          raise
         end
 
         def host_keys
@@ -98,12 +107,16 @@ module Net
           end
         end
 
+        def pubkey_algorithms
+          algorithms[:pubkey_algorithms]
+        end
+
         # Returns the host (and possibly IP address) in a format compatible with
         # SSH known-host files.
         def host_as_string
           @host_as_string ||= begin
-            string = "#{host}"
-            string = "[#{string}]:#{port}" if port != DEFAULT_PORT
+            string = +"#{host}"
+            string = +"[#{string}]:#{port}" if port != DEFAULT_PORT
 
             peer_ip = socket.peer_ip
 
@@ -188,7 +201,7 @@ module Net
         # read from the queue before the socket is queried.
         def poll_message(mode = :nonblock, consume_queue = true)
           loop do
-            return @queue.shift if consume_queue && @queue.any? && algorithms.allow?(@queue.first)
+            return shift_queue if consume_queue && @queue.any? && algorithms.allow?(@queue.first)
 
             packet = socket.next_packet(mode, options[:timeout])
             return nil if packet.nil?
@@ -206,11 +219,17 @@ module Net
             when DEBUG
               send(packet[:always_display] ? :fatal : :debug) { packet[:message] }
 
+            # We don't advertise ext-info-c, but some servers send EXT_INFO anyway (#955).
+            when EXT_INFO
+              debug { "ignoring EXT_INFO packet" }
+
             when KEXINIT
               algorithms.accept_kexinit(packet)
 
             else
               return packet if algorithms.allow?(packet)
+              # Algorithms#rekey! clears initialized?, so the session id is what marks the first key exchange as done.
+              raise Net::SSH::Exception, "unexpected packet type #{packet.type} during initial key exchange" unless algorithms.session_id
 
               push(packet)
             end
@@ -234,6 +253,11 @@ module Net
         # #poll_message will return packets from the queue in the order they
         # were received.
         def push(packet)
+          @queued_bytes += packet.length
+          if @queue.size >= MAX_QUEUED_PACKETS || @queued_bytes > MAX_QUEUED_BYTES
+            raise Net::SSH::Exception, "too many packets queued during key exchange"
+          end
+
           @queue.push(packet)
         end
 
@@ -276,23 +300,31 @@ module Net
 
         private
 
-        # Compatibility verifier which allows users to keep using
-        # custom verifier code without adding new :verify_signature
-        # method.
-        class CompatibleVerifier
-          def initialize(verifier)
-            @verifier = verifier
-          end
+        def shift_queue
+          packet = @queue.shift
+          @queued_bytes -= packet.length
+          packet
+        end
 
-          def verify(arguments)
-            @verifier.verify(arguments)
-          end
+        # Turns Nagle's algorithm off on the socket, so that a packet written
+        # while the previous one is still unacknowledged goes out right away
+        # instead of waiting for the server's ACK. A ProxyCommand hands the
+        # transport a pipe rather than a socket, and the command on its other
+        # end owns the TCP connection, so there is nothing to set in that case.
+        def set_no_delay
+          return unless socket.respond_to?(:setsockopt)
 
-          def verify_signature(&block)
-            yield
-          end
+          debug { "setting TCP_NODELAY" }
+          socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
         end
 
+        REMOVED_VERIFY_HOST_KEY_VALUES = {
+          false => :never,
+          true => :accept_new_or_local_tunnel,
+          very: :accept_new,
+          secure: :always
+        }.freeze
+
         # Instantiates a new host-key verification class, based on the value of
         # the parameter.
         #
@@ -306,46 +338,29 @@ module Net
         #
         # If the argument happens to respond to :verify and :verify_signature,
         # it is returned directly. Otherwise, an exception is raised.
-        #
-        # Values false, true, and :very were deprecated in
-        # [#595](https://github.com/net-ssh/net-ssh/pull/595)
         def select_host_key_verifier(verifier)
           case verifier
-          when false
-            Kernel.warn('verify_host_key: false is deprecated, use :never')
-            Net::SSH::Verifiers::Never.new
           when :never then
             Net::SSH::Verifiers::Never.new
-          when true
-            Kernel.warn('verify_host_key: true is deprecated, use :accept_new_or_local_tunnel')
-            Net::SSH::Verifiers::AcceptNewOrLocalTunnel.new
           when :accept_new_or_local_tunnel, nil then
             Net::SSH::Verifiers::AcceptNewOrLocalTunnel.new
-          when :very
-            Kernel.warn('verify_host_key: :very is deprecated, use :accept_new')
-            Net::SSH::Verifiers::AcceptNew.new
           when :accept_new then
             Net::SSH::Verifiers::AcceptNew.new
-          when :secure then
-            Kernel.warn('verify_host_key: :secure is deprecated, use :always')
-            Net::SSH::Verifiers::Always.new
           when :always then
             Net::SSH::Verifiers::Always.new
+          when *REMOVED_VERIFY_HOST_KEY_VALUES.keys
+            raise ArgumentError,
+                  "verify_host_key: #{verifier.inspect} has been removed, use #{REMOVED_VERIFY_HOST_KEY_VALUES[verifier].inspect}"
           else
-            if verifier.respond_to?(:verify)
-              if verifier.respond_to?(:verify_signature)
-                verifier
-              else
-                Kernel.warn("Warning: verifier without :verify_signature is deprecated")
-                CompatibleVerifier.new(verifier)
-              end
-            else
-              raise(
-                ArgumentError,
-                "Invalid argument to :verify_host_key (or deprecated " \
-                ":paranoid): #{verifier.inspect}"
-              )
+            raise ArgumentError, "Invalid argument to :verify_host_key: #{verifier.inspect}" unless verifier.respond_to?(:verify)
+
+            unless verifier.respond_to?(:verify_signature)
+              raise ArgumentError,
+                    "verify_host_key verifier #{verifier.inspect} must implement verify_signature(&block): " \
+                    "yield to the block, which checks the server's host key signature, and return its result"
             end
+
+            verifier
           end
         end
       end

data/lib/net/ssh/transport/state.rb

@@ -125,7 +125,7 @@ module Net
           compressor.deflate(data, Zlib::SYNC_FLUSH)
         end
 
-        # Deompresses the data. If no compression is in effect, this will just return
+        # Decompresses the data. If no compression is in effect, this will just return
         # the data unmodified, otherwise it uses #decompressor to decompress the data.
         def decompress(data)
           data = data.to_s

data/lib/net/ssh/verifiers/always.rb

@@ -19,10 +19,8 @@ module Net
           # We've never seen this host before, so raise an exception.
           process_cache_miss(host_keys, arguments, HostKeyUnknown, "is unknown") if host_keys.empty?
 
-          # If we found any matches, check to see that the key type and
-          # blob also match.
-
-          found = host_keys.any? do |key|
+          # Find the known-hosts entry whose key matches the presented certificate.
+          found_key = host_keys.find do |key|
             if key.respond_to?(:matches_key?)
               key.matches_key?(arguments[:key])
             else
@@ -30,11 +28,17 @@ module Net
             end
           end
 
-          # If a match was found, return true. Otherwise, raise an exception
-          # indicating that the key was not recognized.
-          process_cache_miss(host_keys, arguments, HostKeyMismatch, "does not match") unless found
+          # No matching entry found — key is not recognized.
+          process_cache_miss(host_keys, arguments, HostKeyMismatch, "does not match") unless found_key
+
+          # For @cert-authority entries, enforce the certificate constraints
+          # OpenSSH checks in sshkey_cert_check_authority. A certificate signed by
+          # the trusted CA but failing any of these is rejected with
+          # HostKeyMismatch (not HostKeyUnknown) so AcceptNew does not swallow the
+          # failure and remember the rejected certificate.
+          verify_certificate!(found_key, host_keys, arguments)
 
-          found
+          true
         end
 
         def verify_signature(&block)
@@ -43,6 +47,37 @@ module Net
 
         private
 
+        # Enforces the @cert-authority certificate constraints for entries that
+        # implement them (Net::SSH::HostKeyEntries::CertAuthority). Non-certificate
+        # entries do not respond to these predicates and are left untouched.
+        def verify_certificate!(entry, host_keys, arguments)
+          cert = arguments[:key]
+
+          if entry.respond_to?(:matches_validity?) && !entry.matches_validity?(cert)
+            reason = if cert.valid_before && cert.valid_before < Time.now
+                       "Certificate has expired"
+                     else
+                       "Certificate is not yet valid"
+                     end
+            process_cache_miss(host_keys, arguments, HostKeyMismatch, reason)
+          end
+
+          if entry.respond_to?(:matches_principal?) && !entry.matches_principal?(cert, host_keys.hostname)
+            process_cache_miss(host_keys, arguments, HostKeyMismatch,
+                               "Certificate invalid: name is not a listed principal")
+          end
+
+          if entry.respond_to?(:matches_type?) && !entry.matches_type?(cert)
+            process_cache_miss(host_keys, arguments, HostKeyMismatch,
+                               "Certificate invalid: not a host certificate")
+          end
+
+          return unless entry.respond_to?(:critical_options_supported?) && !entry.critical_options_supported?(cert)
+
+          process_cache_miss(host_keys, arguments, HostKeyMismatch,
+                             "Certificate invalid: unsupported critical option")
+        end
+
         def process_cache_miss(host_keys, args, exc_class, message)
           exception = exc_class.new("fingerprint #{args[:fingerprint]} " +
                                     "#{message} for #{host_keys.host.inspect}")

data/lib/net/ssh/version.rb

@@ -46,13 +46,13 @@ module Net
       end
 
       # The major component of this version of the Net::SSH library
-      MAJOR = 7
+      MAJOR = 8
 
       # The minor component of this version of the Net::SSH library
-      MINOR = 2
+      MINOR = 0
 
       # The tiny component of this version of the Net::SSH library
-      TINY  = 3
+      TINY  = 4
 
       # The prerelease component of this version of the Net::SSH library
       # nil allowed

data/lib/net/ssh.rb

@@ -1,7 +1,3 @@
-# Make sure HOME is set, regardless of OS, so that File.expand_path works
-# as expected with tilde characters.
-ENV['HOME'] ||= ENV['HOMEPATH'] ? "#{ENV['HOMEDRIVE']}#{ENV['HOMEPATH']}" : Dir.pwd
-
 require 'logger'
 require 'etc'
 require 'shellwords'
@@ -12,6 +8,7 @@ require 'net/ssh/loggable'
 require 'net/ssh/transport/session'
 require 'net/ssh/authentication/session'
 require 'net/ssh/connection/session'
+require 'net/ssh/multiplex'
 require 'net/ssh/prompt'
 
 module Net
@@ -66,14 +63,15 @@ module Net
       auth_methods bind_address compression compression_level config
       encryption forward_agent hmac host_key identity_agent remote_user
       keepalive keepalive_interval keepalive_maxcount kex keys key_data
-      keycerts keycert_data languages logger paranoid password port proxy
+      keycerts keycert_data languages logger password port proxy
       rekey_blocks_limit rekey_limit rekey_packet_limit timeout verbose
       known_hosts global_known_hosts_file user_known_hosts_file host_key_alias
       host_name user properties passphrase keys_only max_pkt_size
       max_win_size send_env set_env use_agent number_of_password_prompts
       append_all_supported_algorithms non_interactive password_prompt
       agent_socket_factory minimum_dh_bits verify_host_key
-      fingerprint_hash check_host_ip pubkey_algorithms
+      fingerprint_hash check_host_ip pubkey_algorithms no_delay
+      control_master control_path preopen_channels
     ]
 
     # The standard means of starting a new SSH connection. When used with a
@@ -102,24 +100,62 @@ module Net
     #     ssh.loop
     #   end
     #
-    # This method accepts the following options (all are optional):
+    # This method accepts the following options (all are optional). Omit an
+    # option to use its default or ssh_config value; passing +nil+ (or an array
+    # containing +nil+) raises ArgumentError, except for :password,
+    # :passphrase, :logger and :password_prompt, where +nil+ means the default.
     #
     # * :auth_methods => an array of authentication methods to try
     # * :bind_address => the IP address on the connecting machine to use in
     #   establishing connection. (:bind_address is discarded if :proxy
     #   is set.)
-    # * :check_host_ip => Also ckeck IP address when connecting to remote host.
+    # * :check_host_ip => Also check IP address when connecting to remote host.
     #   Defaults to +true+.
     # * :compression => the compression algorithm to use, or +true+ to use
     #   whatever is supported.
     # * :compression_level => the compression level to use when sending data
+    # * :control_master => set to +:auto+ to run the session through an
+    #   already running OpenSSH ControlMaster for the same host, port and user
+    #   (started e.g. with <tt>ssh -M</tt> or <tt>ControlMaster auto</tt>),
+    #   using its proxy mode (OpenSSH 7.4 or later). This skips the TCP
+    #   connection, key exchange and authentication. If there is no usable
+    #   master (no ControlPath, no socket, refused, timed out, owned by another
+    #   user) Net::SSH logs why and connects as usual; it never starts a master
+    #   itself. The master's own settings then apply instead of the options
+    #   for setting up a connection (:keys, :key_data, :password, :passphrase,
+    #   :auth_methods, :verify_host_key, :known_hosts, :host_key, :kex,
+    #   :encryption, :hmac, :compression, :rekey_*, :proxy, :keepalive and the
+    #   like); explicitly passed ones are named at info level. Over the
+    #   master, remote port forwarding (Service::Forward#remote and
+    #   #cancel_remote) raises Net::SSH::NotSupportedOverControlMaster, as the
+    #   master consumes the global request reply, so success, failure and the
+    #   port allocated for port 0 can't be observed; other global requests
+    #   raise it too. Agent and X11 forwarding requests raise it
+    #   too, and :forward_agent is ignored (logged at info level), because the
+    #   master serves them from its own agent or display only if it has
+    #   ForwardAgent or ForwardX11 enabled itself, and rejects them otherwise.
+    #   Keepalive and rekeying are left to the master. ssh_config's
+    #   ControlMaster is ignored, only this option enables it. An invalid
+    #   ControlPath raises ArgumentError. A missing or stale socket is logged
+    #   at info level, a socket that can't be used (another owner, refused,
+    #   wrong protocol, timed out) at warn level. Has no effect on Windows.
+    #   Defaults to +false+.
+    # * :control_path => the ControlMaster socket to use with
+    #   :control_master, with the same ~, ${ENV} and % tokens as ssh_config's
+    #   ControlPath (%C, %d, %h, %i, %j, %k, %L, %l, %n, %p, %r, %u, %%).
+    #   The master at that path decides which host and user the session is
+    #   connected to, so a fixed path without %h, %p, %r or %C sends every
+    #   host through the same master and the explicitly passed host key and
+    #   authentication options are ignored. Defaults to ControlPath from
+    #   ssh_config; +"none"+ disables the master.
     # * :config => set to +true+ to load the default OpenSSH config files
     #   (~/.ssh/config, /etc/ssh_config), or to +false+ to not load them, or to
     #   a file-name (or array of file-names) to load those specific configuration
     #   files. Defaults to +true+.
     # * :encryption => the encryption cipher (or ciphers) to use
     # * :forward_agent => set to true if you want the SSH agent connection to
-    #   be forwarded
+    #   be forwarded. Ignored for a session through a ControlMaster (see
+    #   :control_master).
     # * :known_hosts => a custom object holding known hosts records.
     #   It must implement #search_for and `add` in a similiar manner as KnownHosts.
     # * :global_known_hosts_file => the location of the global known hosts
@@ -141,7 +177,11 @@ module Net
     #   Defaults to +300+ seconds.
     # * :keepalive_maxcount => the maximun number of keepalive packet miss allowed.
     #   Defaults to 3
-    # * :kex => the key exchange algorithm (or algorithms) to use
+    # * :kex => the key exchange algorithm (or algorithms) to use. Like
+    #   KexAlgorithms, entries starting with +, - or ^ modify the default list.
+    #   diffie-hellman-group14-sha1 is supported but not offered unless listed
+    #   here (e.g. '+diffie-hellman-group14-sha1') or
+    #   :append_all_supported_algorithms is set.
     # * :keys => an array of file names of private keys to use for publickey
     #   and hostbased authentication
     # * :keycerts => an array of file names of key certificates to use
@@ -159,24 +199,44 @@ module Net
     #   packet. Default is 0x8000 (32768 bytes). Increase to 0x10000 (65536 bytes)
     #   for better performance if your SSH server supports it (most do).
     # * :max_win_size => maximum size we tell the other side that is supported for
-    #   the window.
+    #   the window, i.e. how much the server may send on a channel before net-ssh
+    #   reads it. Default is 0x200000 (2 MB), as in OpenSSH. Smaller values limit
+    #   how much data is in flight; some servers (e.g. Mikrotik) truncate output
+    #   when the window is small.
+    # * :minimum_dh_bits => the smallest group, in bits, accepted from the server
+    #   in diffie-hellman-group-exchange key exchange. Defaults to 2048, as in
+    #   OpenSSH; lower it (e.g. to 1024) only to reach legacy servers that offer
+    #   nothing larger.
+    # * :no_delay => turns Nagle's algorithm off on the connection's socket
+    #   (TCP_NODELAY), so a packet written while the previous one is still
+    #   unacknowledged is sent right away instead of waiting for the server's
+    #   ACK. OpenSSH does the same for every connection. Set to +false+ to keep
+    #   Nagle's algorithm on. Has no effect when the socket comes from a
+    #   ProxyCommand, whose command owns the TCP connection. Defaults to +true+.
     # * :non_interactive => set to true if your app is non interactive and prefers
     #   authentication failure vs password prompt. Non-interactive applications
     #   should set it to true to prefer failing a password/etc auth methods vs.
     #   asking for password.
-    # * :paranoid => deprecated alias for :verify_host_key
     # * :passphrase => the passphrase to use when loading a private key (default
     #   is +nil+, for no passphrase)
     # * :password => the password to use to login
     # * :port => the port to use when connecting to the remote host
+    # * :preopen_channels => set to +true+ to keep one spare "session" channel
+    #   open, so that Net::SSH::Connection::Session#open_channel can hand it
+    #   out at once and a command that waits for the previous one to finish
+    #   costs one round trip instead of two. The spare counts against the
+    #   server's MaxSessions; if the server refuses it, pre-opening stops for
+    #   the session. Defaults to +false+.
     # * :properties => a hash of key/value pairs to add to the new connection's
     #   properties (see Net::SSH::Connection::Session#properties)
     # * :proxy => a proxy instance (see Proxy) to use when connecting
-    # * :pubkey_algorithms => the public key authentication algorithms to use for
-    #   this connection. Valid values are 'rsa-sha2-256-cert-v01@openssh.com',
-    #   'ssh-rsa-cert-v01@openssh.com', 'rsa-sha2-256', 'ssh-rsa'. Currently, this
-    #   option is only used for RSA public key authentication and ignored for other
-    #   types.
+    # * :pubkey_algorithms => the public key authentication algorithms to offer,
+    #   in order of preference (e.g. %w[ssh-ed25519 rsa-sha2-512 rsa-sha2-256]).
+    #   Keys whose type isn't listed are skipped. Like PubkeyAcceptedAlgorithms,
+    #   entries starting with +, - or ^ modify the default list. ssh-rsa (SHA-1),
+    #   ssh-rsa-cert-v01@openssh.com and ssh-dss are supported but not offered
+    #   unless listed here (e.g. '+ssh-rsa') or :append_all_supported_algorithms
+    #   is set.
     # * :rekey_blocks_limit => the max number of blocks to process before rekeying
     # * :rekey_limit => the max number of bytes to process before rekeying
     # * :rekey_packet_limit => the max number of packets to process before rekeying
@@ -188,7 +248,8 @@ module Net
     # * :user => the user name to log in as; this overrides the +user+
     #   parameter, and is primarily only useful when provided via an SSH
     #   configuration file.
-    # * :remote_user => used for substitution into the '%r' part of a ProxyCommand
+    # * :remote_user => used for substitution into the '%r' part of a ProxyCommand;
+    #   defaults to the user name the connection logs in as.
     # * :user_known_hosts_file => the location of the user known hosts file.
     #   Set to an array to specify multiple user known hosts files.
     #   Defaults to %w(~/.ssh/known_hosts ~/.ssh/known_hosts2).
@@ -200,7 +261,9 @@ module Net
     #   default. The symbols :debug, :info, :warn, :error, and :fatal are also
     #   supported and are translated to the corresponding Logger constant.
     # * :append_all_supported_algorithms => set to +true+ to append all supported
-    #   algorithms by net-ssh. Was the default behaviour until 2.10
+    #   algorithms by net-ssh, except the +none+ cipher and MAC, which must be
+    #   named explicitly (e.g. encryption: '+none'). Was the default behaviour
+    #   until 2.10
     # * :number_of_password_prompts => Number of prompts for the password
     #   authentication method defaults to 3 set to 0 to disable prompt for
     #   password auth method
@@ -215,21 +278,32 @@ module Net
     #   * :accept_new_or_local_tunnel (insecure) ::Net::SSH::Verifiers::AcceptNewOrLocalTunnel
     #   * :accept_new (insecure) ::Net::SSH::Verifiers::AcceptNew
     #   * :always (secure) ::Net::SSH::Verifiers::Always
-    #   You can also provide an own Object which responds to +verify+. The argument
-    #   given to +verify+ is a hash consisting of the +:key+, the +:key_blob+,
-    #   the +:fingerprint+ and the +:session+. Returning true accepts the host key,
-    #   returning false declines it and closes the connection.
+    #   You can also provide an own Object which responds to +verify+ and
+    #   +verify_signature+. The argument given to +verify+ is a hash consisting
+    #   of the +:key+, the +:key_blob+, the +:fingerprint+ and the +:session+.
+    #   Returning true accepts the host key, returning false declines it and
+    #   closes the connection. +verify_signature+ is given a block that checks
+    #   the server's host key signature and must return the block's result.
     # * :fingerprint_hash => 'MD5' or 'SHA256', defaults to 'SHA256'
     # If +user+ parameter is nil it defaults to USER from ssh_config, or
     # local username
     def self.start(host, user = nil, options = {}, &block)
+      if options.key?(:paranoid)
+        raise ArgumentError, ":paranoid has been removed, use :verify_host_key (same values)"
+      end
+
       invalid_options = options.keys - VALID_OPTIONS
       if invalid_options.any?
         raise ArgumentError, "invalid option(s): #{invalid_options.join(', ')}"
       end
 
+      reject_nil_options(options)
+      Multiplex.validate_options!(options)
+      explicit_options = options.keys
+      host_arg = host
+
+      options = options.dup
       assign_defaults(options)
-      _sanitize_options(options)
 
       options[:user] = user if user
       options = configuration_for(host, options.fetch(:config, true)).merge(options)
@@ -241,8 +315,6 @@ module Net
         options[:number_of_password_prompts] = 0
       end
 
-      _support_deprecated_option_paranoid(options)
-
       if options[:verbose]
         options[:logger].level = case options[:verbose]
                                  when Integer then options[:verbose]
@@ -255,26 +327,35 @@ module Net
                                  end
       end
 
-      transport = Transport::Session.new(host, options)
-      auth = Authentication::Session.new(transport, options)
-
       user = options.fetch(:user, user) || Etc.getpwuid.name
-      if auth.authenticate("ssh-connection", user, options[:password])
-        connection = Connection::Session.new(transport, options)
-        if block_given?
-          begin
-            yield connection
-          ensure
-            connection.close unless connection.closed?
-          end
-        else
-          return connection
+      options[:remote_user] ||= user
+
+      connection = Multiplex.connect(host_arg, host, user, options, explicit: explicit_options) if options[:control_master]
+      connection ||= connect_directly(host, user, options)
+
+      if block_given?
+        begin
+          yield connection
+        ensure
+          connection.close unless connection.closed?
         end
       else
+        connection
+      end
+    end
+
+    def self.connect_directly(host, user, options)
+      transport = Transport::Session.new(host, options)
+      auth = Authentication::Session.new(transport, options)
+
+      unless auth.authenticate("ssh-connection", user, options[:password])
         transport.close
         raise AuthenticationFailed, "Authentication failed for user #{user}@#{host}"
       end
+
+      Connection::Session.new(transport, options)
     end
+    private_class_method :connect_directly
 
     # Returns a hash of the configuration options for the given host, as read
     # from the SSH configuration file(s). If +use_ssh_config+ is true (the
@@ -308,31 +389,35 @@ module Net
       end
     end
 
-    def self._sanitize_options(options)
-      invalid_option_values = [nil, [nil]]
-      unless (options.values & invalid_option_values).empty?
-        nil_options = options.select { |_k, v| invalid_option_values.include?(v) }.map(&:first)
-        Kernel.warn "#{caller_locations(2, 1)[0]}: Passing nil, or [nil] to Net::SSH.start is deprecated for keys: #{nil_options.join(', ')}"
-      end
-    end
-    private_class_method :_sanitize_options
+    NIL_ALLOWED_OPTIONS = %i[password passphrase logger password_prompt].freeze
 
-    def self._support_deprecated_option_paranoid(options)
-      if options.key?(:paranoid)
-        Kernel.warn(
-          ":paranoid is deprecated, please use :verify_host_key. Supported " \
-          "values are exactly the same, only the name of the option has changed."
-        )
-        if options.key?(:verify_host_key)
-          Kernel.warn(
-            "Both :paranoid and :verify_host_key were specified. " \
-            ":verify_host_key takes precedence, :paranoid will be ignored."
-          )
-        else
-          options[:verify_host_key] = options.delete(:paranoid)
-        end
-      end
+    NIL_OPTION_HINTS = {
+      config: "config: false to skip ssh_config files",
+      proxy: "proxy: false to connect without a proxy",
+      keys: "keys: [] to use no key files",
+      use_agent: "use_agent: false to not use ssh-agent",
+      forward_agent: "forward_agent: false to not forward ssh-agent",
+      keepalive: "keepalive: false to send no keepalives",
+      compression: "compression: false to disable compression",
+      control_master: "control_master: false to not use a ControlMaster",
+      control_path: "control_path: 'none' to not use a ControlMaster socket",
+      send_env: "send_env: [] to send no environment variables",
+      set_env: "set_env: {} to set no environment variables"
+    }.freeze
+    private_constant :NIL_ALLOWED_OPTIONS, :NIL_OPTION_HINTS
+
+    def self.reject_nil_options(options)
+      nil_keys = options.select do |key, value|
+        !NIL_ALLOWED_OPTIONS.include?(key) && (value.nil? || (value.is_a?(Array) && value.include?(nil)))
+      end.keys
+      return if nil_keys.empty?
+
+      message = "nil is not allowed for #{nil_keys.map(&:inspect).join(', ')}; " \
+                "omit #{nil_keys.one? ? 'it' : 'them'} to use the default or ssh_config value"
+      hints = NIL_OPTION_HINTS.values_at(*nil_keys).compact
+      message += ", or pass #{hints.join(', or ')}" if hints.any?
+      raise ArgumentError, message
     end
-    private_class_method :_support_deprecated_option_paranoid
+    private_class_method :reject_nil_options
   end
 end