net-ssh 7.3.6 → 8.1.2

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

@@ -56,6 +56,11 @@ module Net
         # The hash of options that were given to the object at initialization.
         attr_reader :options
 
+        # The signature algorithms the server accepts for publickey
+        # authentication, from its RFC 8308 server-sig-algs extension, or nil if
+        # it did not send one.
+        attr_reader :server_sig_algs
+
         # Instantiates a new transport layer abstraction. This will block until
         # the initial key exchange completes, leaving you with a ready-to-use
         # transport session.
@@ -66,6 +71,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])
@@ -79,21 +85,24 @@ module Net
 
           @socket.extend(PacketStream)
           @socket.logger = @logger
+          set_no_delay unless options[:no_delay] == false
 
           debug { "connection established" }
 
           @queue = []
           @queued_bytes = 0
 
-          @host_key_verifier = select_host_key_verifier(options[:verify_host_key])
-
           @server_version = ServerVersion.new(socket, logger, options[:timeout])
 
           @algorithms = Algorithms.new(self, options)
           @algorithms.start
           wait { algorithms.initialized? }
         rescue Errno::ETIMEDOUT
+          @socket&.close
           raise Net::SSH::ConnectionTimeout
+        rescue StandardError
+          @socket&.close
+          raise
         end
 
         def host_keys
@@ -103,6 +112,10 @@ 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
@@ -211,12 +224,16 @@ module Net
             when DEBUG
               send(packet[:always_display] ? :fatal : :debug) { packet[:message] }
 
+            when EXT_INFO
+              accept_ext_info(packet)
+
             when KEXINIT
               algorithms.accept_kexinit(packet)
 
             else
               return packet if algorithms.allow?(packet)
-              raise Net::SSH::Exception, "unexpected packet type #{packet.type} during initial key exchange" unless algorithms.initialized?
+              # 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
@@ -287,29 +304,45 @@ module Net
 
         private
 
+        # Parses an RFC 8308 EXT_INFO packet, which servers send after the first
+        # NEWKEYS and possibly again just before USERAUTH_SUCCESS.
+        def accept_ext_info(packet)
+          count = packet.read_long or raise Net::SSH::Exception, "malformed EXT_INFO packet from server"
+          count.times do
+            name = packet.read_string
+            value = packet.read_string
+            raise Net::SSH::Exception, "malformed EXT_INFO packet from server" if name.nil? || value.nil?
+
+            debug { "EXT_INFO #{name}: #{value}" }
+            @server_sig_algs = value.split(",") if name == "server-sig-algs"
+          end
+        end
+
         def shift_queue
           packet = @queue.shift
           @queued_bytes -= packet.length
           packet
         end
 
-        # 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
+        # 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(arguments)
-            @verifier.verify(arguments)
-          end
-
-          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.
         #
@@ -323,46 +356,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/verifiers/accept_new_or_local_tunnel.rb

@@ -7,11 +7,13 @@ module Net
       # verify a connection if the server is the localhost and the port is a
       # nonstandard port number. Those two conditions will typically mean the
       # connection is being tunnelled through a forwarded port, so the known-hosts
-      # file will not be helpful (in general).
+      # file will not be helpful (in general). A key marked @revoked is refused
+      # either way.
       class AcceptNewOrLocalTunnel < AcceptNew
         # Tries to determine if the connection is being tunnelled, and if so,
         # returns true. Otherwise, performs the standard strict verification.
         def verify(arguments)
+          refuse_revoked!(arguments)
           return true if tunnelled?(arguments)
 
           super

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

@@ -10,10 +10,13 @@ module Net
       # (HostKeyUnknown). This is in contrast to the "Strict" class, which will
       # silently add the key to your known_hosts file. If the server does appear at
       # least once, but the key given does not match any known for the server, an
-      # exception will be raised (HostKeyMismatch).
+      # exception will be raised (HostKeyMismatch). A key marked @revoked in a
+      # host file is always refused (HostKeyRevoked).
       # Otherwise, this returns true.
       class Always
         def verify(arguments)
+          refuse_revoked!(arguments)
+
           host_keys = arguments[:session].host_keys
 
           # We've never seen this host before, so raise an exception.
@@ -47,13 +50,22 @@ module Net
 
         private
 
+        # Custom :known_hosts objects may return a host_keys collection with no
+        # revocation support.
+        def refuse_revoked!(arguments)
+          host_keys = arguments[:session].host_keys
+          return unless host_keys.respond_to?(:revoked?) && host_keys.revoked?(arguments[:key])
+
+          exception = HostKeyRevoked.new("fingerprint #{arguments[:fingerprint]} " +
+                                         "is revoked for #{host_keys.host.inspect}")
+          exception.data = arguments
+          raise exception
+        end
+
         # 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)
-          # Plain keys carry no certificate constraints, and respond_to? on this delegator prints a deprecation warning (#1026).
-          return if entry.is_a?(Net::SSH::HostKeyEntries::PubKey)
-
           cert = arguments[:key]
 
           if entry.respond_to?(:matches_validity?) && !entry.matches_validity?(cert)

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

@@ -3,7 +3,8 @@ module Net
     module Verifiers
       # This host key verifier simply allows every key it sees, without
       # any verification. This is simple, but very insecure because it
-      # exposes you to MiTM attacks.
+      # exposes you to MiTM attacks. It does not read the known hosts files,
+      # so it accepts keys marked @revoked as well.
       class Never
         # Returns true.
         def verify(arguments)

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 = 3
+      MINOR = 1
 
       # The tiny component of this version of the Net::SSH library
-      TINY  = 6
+      TINY  = 2
 
       # The prerelease component of this version of the Net::SSH library
       # nil allowed

data/lib/net/ssh.rb

@@ -8,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
@@ -62,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
+      prompt_without_tty agent_socket_factory minimum_dh_bits verify_host_key
+      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
@@ -98,7 +100,10 @@ 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
@@ -109,13 +114,48 @@ module Net
     # * :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
@@ -137,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
@@ -155,24 +199,51 @@ 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
+    #   asking for password. Like OpenSSH, Net::SSH never prompts when $stdin is
+    #   not a TTY (e.g. in a background job), so it defaults to +true+ then,
+    #   unless :password_prompt or :prompt_without_tty is given or an
+    #   SSH_ASKPASS program can be used (see Net::SSH::Prompt.askpass).
     # * :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+.
+    # * :prompt_without_tty => set to +true+ to prompt for passwords, key
+    #   passphrases and keyboard-interactive responses on $stdout/$stdin even
+    #   when $stdin is not a TTY, e.g. to read a password piped into the
+    #   process. 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
@@ -184,7 +255,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).
@@ -196,7 +268,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
@@ -211,24 +285,35 @@ 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)
+      options = configuration_for(host, options.fetch(:config, true), user: options[:user]).merge(options)
       host = options.fetch(:host_name, host)
 
       options[:check_host_ip] = true unless options.key?(:check_host_ip)
@@ -237,8 +322,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]
@@ -251,26 +334,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
@@ -280,15 +372,17 @@ module Net
     # be a file name (or array of file names) of SSH configuration file(s)
     # to read.
     #
+    # +user+ is the explicitly requested remote user, matched by <tt>Match User</tt>.
+    #
     # See Net::SSH::Config for the full description of all supported options.
-    def self.configuration_for(host, use_ssh_config)
+    def self.configuration_for(host, use_ssh_config, user: nil)
       files = case use_ssh_config
               when true then Net::SSH::Config.expandable_default_files
               when false, nil then return {}
               else Array(use_ssh_config)
               end
 
-      Net::SSH::Config.for(host, files)
+      Net::SSH::Config.for(host, files, user: user)
     end
 
     def self.assign_defaults(options)
@@ -297,6 +391,9 @@ module Net
         options[:logger].level = Logger::FATAL
       end
 
+      unless options[:password_prompt] || options[:prompt_without_tty] || Prompt.can_ask?
+        options[:non_interactive] = true
+      end
       options[:password_prompt] ||= Prompt.default(options)
 
       %i[password passphrase].each do |key|
@@ -304,31 +401,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