Rename :paranoid to :verify_host_key

The words we choose matter. By using the word "paranoid", we make
fun of people who care about security. Instead, we should encourage
security in our community, or at least use a neutral term.

In this patch, we choose the neutral wording that is used by the SSH
manual page:

> the server must be able to verify the client's host key
> (see the description of /etc/ssh/ssh_known_hosts and
> ~/.ssh/known_hosts, below) for login to be permitted.

3 files changed, 44 insertions, 15 deletions

diff --git a/lib/net/ssh.rb b/lib/net/ssh.rb
index 899bd7e..f3d88c3 100644
--- a/lib/net/ssh.rb
+++ b/lib/net/ssh.rb
@@ -72,7 +72,7 @@ module Net
       :host_name, :user, :properties, :passphrase, :keys_only, :max_pkt_size,
       :max_win_size, :send_env, :use_agent, :number_of_password_prompts,
       :append_all_supported_algorithms, :non_interactive, :password_prompt,
-      :agent_socket_factory, :minimum_dh_bits
+      :agent_socket_factory, :minimum_dh_bits, :verify_host_key
     ]
 
     # The standard means of starting a new SSH connection. When used with a
@@ -157,12 +157,7 @@ module Net
     #   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 => either false, true, :very, or :secure specifying how
-    #   strict host-key verification should be (in increasing order here).
-    #   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.
+    # * :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
@@ -199,6 +194,13 @@ module Net
     # * :agent_socket_factory => enables the user to pass a lambda/block that will serve as the socket factory
     #    Net::SSH::start(user,host,agent_socket_factory: ->{ UNIXSocket.open('/foo/bar') })
     #    example: ->{ UNIXSocket.open('/foo/bar')}
+    # * :verify_host_key => either false, true, :very, or :secure specifying how
+    #   strict host-key verification should be (in increasing order here).
+    #   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.
+    #
     # If +user+ parameter is nil it defaults to USER from ssh_config, or
     # local username
     def self.start(host, user=nil, options={}, &block)
@@ -218,6 +220,8 @@ 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]
@@ -291,5 +295,23 @@ module Net
       end
     end
     private_class_method :_sanitize_options
+
+    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
+    end
+    private_class_method :_support_deprecated_option_paranoid
   end
 end
diff --git a/lib/net/ssh/test.rb b/lib/net/ssh/test.rb
index cd623a8..2714c8a 100644
--- a/lib/net/ssh/test.rb
+++ b/lib/net/ssh/test.rb
@@ -71,7 +71,10 @@ module Net; module SSH
     # in these tests. It is a fully functional SSH transport session, operating
     # over a mock socket (#socket).
     def transport(options={})
-      @transport ||= Net::SSH::Transport::Session.new(options[:host] || "localhost", options.merge(kex: "test", host_key: "ssh-rsa", paranoid: false, proxy: socket(options)))
+      @transport ||= Net::SSH::Transport::Session.new(
+        options[:host] || "localhost",
+        options.merge(kex: "test", host_key: "ssh-rsa", verify_host_key: false, proxy: socket(options))
+      )
     end
 
     # First asserts that a story has been described (see #story). Then yields,
@@ -86,4 +89,4 @@ module Net; module SSH
     end
   end
 
-end; end
\ No newline at end of file
+end; end
diff --git a/lib/net/ssh/transport/session.rb b/lib/net/ssh/transport/session.rb
index 0804867..9470a33 100644
--- a/lib/net/ssh/transport/session.rb
+++ b/lib/net/ssh/transport/session.rb
@@ -78,7 +78,7 @@ module Net; module SSH; module Transport
 
       @queue = []
 
-      @host_key_verifier = select_host_key_verifier(options[:paranoid])
+      @host_key_verifier = select_host_key_verifier(options[:verify_host_key])
 
 
       @server_version = ServerVersion.new(socket, logger, options[:timeout])
@@ -281,8 +281,8 @@ module Net; module SSH; module Transport
       # strict Secure verifier is returned. If the argument happens to respond
       # to :verify, it is returned directly. Otherwise, an exception
       # is raised.
-      def select_host_key_verifier(paranoid)
-        case paranoid
+      def select_host_key_verifier(verify_host_key)
+        case verify_host_key
         when true, nil then
           Net::SSH::Verifiers::Lenient.new
         when false then
@@ -292,10 +292,14 @@ module Net; module SSH; module Transport
         when :secure then
           Net::SSH::Verifiers::Secure.new
         else
-          if paranoid.respond_to?(:verify)
-            paranoid
+          if verify_host_key.respond_to?(:verify)
+            verify_host_key
           else
-            raise ArgumentError, "argument to :paranoid is not valid: #{paranoid.inspect}"
+            raise(
+              ArgumentError,
+              "Invalid argument to :verify_host_key (or deprecated " \
+              ":paranoid): #{verify_host_key.inspect}"
+            )
           end
         end
       end