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.

5 files changed, 60 insertions, 27 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 863410c..e1cb87d 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,3 +1,7 @@
+=== Unreleased
+
+ * Deprecate `:paranoid` in favor of `:verify_host_key`
+
 === 4.1.0
 === 4.1.0.rc1
 
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
diff --git a/test/transport/test_session.rb b/test/transport/test_session.rb
index 419dd00..6131177 100644
--- a/test/transport/test_session.rb
+++ b/test/transport/test_session.rb
@@ -20,29 +20,29 @@ module Transport
       assert_instance_of Net::SSH::Verifiers::Lenient, session.host_key_verifier
     end
 
-    def test_paranoid_true_uses_lenient_verifier
-      assert_instance_of Net::SSH::Verifiers::Lenient, session(paranoid: true).host_key_verifier
+    def test_verify_host_key_true_uses_lenient_verifier
+      assert_instance_of Net::SSH::Verifiers::Lenient, session(verify_host_key: true).host_key_verifier
     end
 
-    def test_paranoid_very_uses_strict_verifier
-      assert_instance_of Net::SSH::Verifiers::Strict, session(paranoid: :very).host_key_verifier
+    def test_verify_host_key_very_uses_strict_verifier
+      assert_instance_of Net::SSH::Verifiers::Strict, session(verify_host_key: :very).host_key_verifier
     end
 
-    def test_paranoid_secure_uses_secure_verifier
-      assert_instance_of Net::SSH::Verifiers::Secure, session(paranoid: :secure).host_key_verifier
+    def test_verify_host_key_secure_uses_secure_verifier
+      assert_instance_of Net::SSH::Verifiers::Secure, session(verify_host_key: :secure).host_key_verifier
     end
 
-    def test_paranoid_false_uses_null_verifier
-      assert_instance_of Net::SSH::Verifiers::Null, session(paranoid: false).host_key_verifier
+    def test_verify_host_key_false_uses_null_verifier
+      assert_instance_of Net::SSH::Verifiers::Null, session(verify_host_key: false).host_key_verifier
     end
 
-    def test_unknown_paranoid_value_raises_exception_if_value_does_not_respond_to_verify
-      assert_raises(ArgumentError) { session(paranoid: :bogus).host_key_verifier }
+    def test_unknown_verify_host_key_value_raises_exception_if_value_does_not_respond_to_verify
+      assert_raises(ArgumentError) { session(verify_host_key: :bogus).host_key_verifier }
     end
 
-    def test_paranoid_value_responding_to_verify_should_pass_muster
+    def test_verify_host_key_value_responding_to_verify_should_pass_muster
       object = stub("thingy", verify: true)
-      assert_equal object, session(paranoid: object).host_key_verifier
+      assert_equal object, session(verify_host_key: object).host_key_verifier
     end
 
     def test_host_as_string_should_return_host_and_ip_when_port_is_default