hrr_rb_ssh 0.3.0.pre1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08be357edfafa61b913c4f28f6d97a29e7aa0c94eaef933a3ea2dce9bc51c9a3'
-  data.tar.gz: 4b87367e0ac95045fcfac372fd1e8735e896436a2d26a2987b94daad2244379f
+  metadata.gz: 781a7427bc3d26dcddba2be4a74f685d26ecc867fe6a1d937cd19e3b56cd9477
+  data.tar.gz: c1ea1ee12f012d1cf66a23518049a9ce127a1ded1536c735330b6f7e3ad22d7d
 SHA512:
-  metadata.gz: f830b32cb263e45ca84596b310889cee768fcf870fc78093c818d2a8dff9fa59c09c334bb7942bf56b344d6d9ce9bcff609962880fcd7e4ac9b74aa1a703c8a5
-  data.tar.gz: 31f317c5fc929b0b04b78fa19d9f85be1f9e4aef4c57474e8fe06039e8f947818eb7e0033da21b80bd9f7e8fa8d3a544c348a468ba31da4cf509812013b2a550
+  metadata.gz: c0c79b9c3d00f49b4e8090ec6cf9aa5e58619d62f4bd46a0d2864c3c29d908a92470f4eda4e9ba1b057f765b98214ddcaa5b44e9cd4de1ecd44639afd89d29bd
+  data.tar.gz: e9c84a3ad17d39972c6950f4da1b92bca351511d5bc220b342ac7d61f7d70631f60c68ecd5ac5d964d76825b5a67027227bb45ac3f2703788c7d7a548359c730

data/.gitignore

@@ -21,7 +21,4 @@ Gemfile.lock
 .ruby-gemset
 
 # additional
-.DS_Store
-*~
-*.swp
 /yang/

data/.travis.yml

@@ -11,6 +11,7 @@ rvm:
   - 2.4
   - 2.5
   - 2.6
+  - 2.7
   - ruby-head
 os:
   - linux

data/README.md

@@ -5,29 +5,40 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/f5dfdb97d72f24ca5939/test_coverage)](https://codeclimate.com/github/hirura/hrr_rb_ssh/test_coverage)
 [![Gem Version](https://badge.fury.io/rb/hrr_rb_ssh.svg)](https://badge.fury.io/rb/hrr_rb_ssh)
 
-hrr_rb_ssh is a pure Ruby SSH 2.0 server implementation.
+hrr_rb_ssh is a pure Ruby SSH 2.0 server and client implementation.
 
-With hrr_rb_ssh, it is possible to write an SSH server easily, and also possible to write an original server side application on secure connection provided by SSH protocol.
+With hrr_rb_ssh, it is possible to write an SSH server easily, and also possible to write an original server side application on secure connection provided by SSH protocol. And it supports to write SSH client as well.
+
+NOTE: ED25519 public key algorithm is now separated from hrr_rb_ssh. Please refer to [hrr_rb_ssh-ed25519](https://github.com/hirura/hrr_rb_ssh-ed25519).
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Usage](#usage)
+    - [Requiring hrr\_rb\_ssh library](#requiring-hrr_rb_ssh-library)
+    - [Logging](#logging)
     - [Writing standard SSH server](#writing-standard-ssh-server)
-        - [Requiring hrr\_rb\_ssh library](#requiring-hrr_rb_ssh-library)
         - [Starting server application](#starting-server-application)
-        - [Logging](#logging)
         - [Registering pre\-generated secret keys for server host key](#registering-pre-generated-secret-keys-for-server-host-key)
         - [Defining authentications](#defining-authentications)
-            - [Password authentication](#password-authentication)
-            - [Publickey authentication](#publickey-authentication)
-            - [Keyboard-interactive authentication](#keyboard-interactive-authentication)
-            - [None authentication (NOT recomended)](#none-authentication-not-recomended)
+            - [Single authentication](#single-authentication)
+                - [Password authentication](#password-authentication)
+                - [Publickey authentication](#publickey-authentication)
+                - [Keyboard-interactive authentication](#keyboard-interactive-authentication)
+                - [None authentication (NOT recomended)](#none-authentication-not-recomended)
+            - [Multi\-step authentication](#multi-step-authentication)
+            - [More flexible authentication](#more-flexible-authentication)
         - [Handling session channel requests](#handling-session-channel-requests)
             - [Reference request handlers](#reference-request-handlers)
             - [Custom request handlers](#custom-request-handlers)
         - [Defining preferred algorithms (optional)](#defining-preferred-algorithms-optional)
         - [Hiding and/or simulating local SSH version](#hiding-and-or-simulating-local-ssh-version)
+    - [Writing SSH client (Experimental)](#writing-ssh-client-experimental)
+        - [Starting SSH connection](#starting-ssh-connection)
+        - [Executing remote commands](#executing-remote-commands)
+            - [exec method](#exec-method)
+            - [shell method](#shell-method)
+            - [subsystem method](#subsystem-method)
     - [Demo](#demo)
 - [Supported Features](#supported-features)
     - [Connection layer](#connection-layer)
@@ -59,9 +70,7 @@ $ gem install hrr_rb_ssh
 
 ## Usage
 
-### Writing standard SSH server
-
-#### Requiring `hrr_rb_ssh` library
+### Requiring `hrr_rb_ssh` library
 
 First of all, `hrr_rb_ssh` library needs to be loaded.
 
@@ -69,6 +78,41 @@ First of all, `hrr_rb_ssh` library needs to be loaded.
 require 'hrr_rb_ssh'
 ```
 
+### Logging
+
+__IMPORTANT__: DEBUG log level outputs all communications between local and remote in human-readable plain-text including password and any secret. Be careful to use logging.
+
+The library provides logging functionality. To enable logging in the library, you are to give a `logger` to `Server.new` or `Client.new`.
+
+```ruby
+HrrRbSsh::Server.new options, logger: logger
+```
+
+or
+
+```ruby
+HrrRbSsh::Client.new target, options, logger: logger
+```
+
+Where, the `logger` variable can be an instance of standard Logger class or user-defined logger class. What the library requires for `logger` variable is that the `logger` instance responds to `#fatal`, `#error`, `#warn`, `#info` and `#debug` with the following syntax.
+
+```ruby
+logger.fatal(progname){ message }
+logger.error(progname){ message }
+logger.warn(progname){ message }
+logger.info(progname){ message }
+logger.debug(progname){ message }
+```
+
+For instance, `logger` variable can be prepared like below.
+
+```ruby
+logger = Logger.new STDOUT
+logger.level = Logger::INFO
+```
+
+### Writing standard SSH server
+
 #### Starting server application
 
 The library is to run on a socket IO. To start SSH server, running a server IO and accepting a connection are required. The 10022 port number is just an example.
@@ -94,31 +138,6 @@ end
 
 Where, an `options` variable is an instance of `Hash`, which has optional (or sometimes almost necessary) values.
 
-#### Logging
-
-__IMPORTANT__: DEBUG log level outputs all communications between local and remote in human-readable plain-text including password and any secret. Be careful to use logging.
-
-The library provides logging functionality. To enable logging of the library, you are to initialize `HrrRbSsh::Logger` class.
-
-```ruby
-HrrRbSsh::Logger.initialize logger
-```
-
-Where, the `logger` variable can be an instance of standard Logger class or user-defined logger class. What `HrrRbSsh::Logger` class requires for `logger` variable is that the `logger` instance responds to `#fatal`, `#error`, `#warn`, `#info` and `#debug`.
-
-For instance, `logger` variable can be prepared like below.
-
-```ruby
-logger = Logger.new STDOUT
-logger.level = Logger::INFO
-```
-
-To disable logging, you can un-initialize `HrrRbSsh::Logger`.
-
-```ruby
-HrrRbSsh::Logger.uninitialize
-```
-
 #### Registering pre-generated secret keys for server host key
 
 By default, server host keys are generated everytime the gem is loaded. To use pre-generated keys, it is possible to register the keys in HrrRbSsh::Transport through `options` variable. The secret key value must be PEM or DER format string. The below is an example of registering ecdsa-sha2-nistp256 secret key. The supported server host key algorithms are listed later in this document.
@@ -138,7 +157,13 @@ EOB
 
 By default, any authentications get failed. To allow users to login to the SSH service, at least one of the authentication methods must be defined and registered into the instance of HrrRbSsh::Authentication through `options` variable.
 
-##### Password authentication
+The library defines a sort of strategies to implement handling authentication.
+
+##### Single authentication
+
+Each authenticator returns `true` (or `HrrRbSsh::Authentication::SUCCESS`) or `false` (or `HrrRbSsh::Authentication::FAILURE`). When it is true, the user is accepted. When it is false, the user is not accepted and a subsequent authenticator is called.
+
+###### Password authentication
 
 Password authentication is the most simple way to allow users to login to the SSH service. Password authentication requires user-name and password.
 
@@ -161,9 +186,11 @@ The `context` variable in password authentication context provides the following
 
 - `#username` : The username that a remote user tries to authenticate
 - `#password` : The password that a remote user tries to authenticate
+- `#variables` : A hash instance that is shared in each authenticator and subsequent session channel request handlers
+- `#vars` : The same object that `#variables` returns
 - `#verify(username, password)` : Returns `true` when username and password arguments match with the context's username and password. Or returns `false` when username and password arguments don't match.
 
-##### Publickey authentication
+###### Publickey authentication
 
 The second one is public key authentication. Public key authentication requires user-name, public key algorithm name, and PEM or DER formed public key.
 
@@ -184,7 +211,7 @@ The `context` variable in public key authentication context provides the `#verif
 
 And public keys that is in OpenSSH public key format is now available. To use OpenSSH public keys, it is easy to use $USER_HOME/.ssh/authorized_keys file.
 
-##### Keyboard-interactive authentication
+###### Keyboard-interactive authentication
 
 The third one is keyboard-interactive authentication. This is also known as challenge-response authentication.
 
@@ -213,7 +240,7 @@ The `#info_request` method takes four arguments: name, instruction, language tag
 
 The responses are listed in the same order as request prompts.
 
-##### None authentication (NOT recomended)
+###### None authentication (NOT recomended)
 
 The last one is none authentication. None authentication is usually NOT used.
 
@@ -232,6 +259,73 @@ options['authentication_none_authenticator'] = auth_none
 
 In none authentication context, `context` variable provides the `#username` method.
 
+##### Multi-step authentication
+
+In this strategy that conbines single authentications, it is possible to implement multi-step authentication. In case that the combination is a publickey authentication method and a password authentication method, it is so-called two-factor authentication.
+
+A return value of each authentication handler can be `HrrRbSsh::Authentication::PARTIAL_SUCCESS`. The value means that the authentication method returns success and another authenticatoin method is requested (i.e. the authentication method is deleted from the list of authentication that can continue, and then the server sends USERAUTH_FAILURE message with the updated list of authentication that can continue and partial success true). When all preferred authentication methods returns `PARTIAL_SUCCESS` (i.e. there is no more authentication that can continue), then the user is treated as authenticated.
+
+```ruby
+auth_preferred_authentication_methods = ["publickey", "password"]
+auth_publickey = HrrRbSsh::Authentication::Authenticator.new { |context|
+  is_verified = some_verification_method(context)
+  if is_verified
+    HrrRbSsh::Authentication::PARTIAL_SUCCESS
+  else
+    false
+  end
+}
+auth_password = HrrRbSsh::Authentication::Authenticator.new { |context|
+  is_verified = some_verification_method(context)
+  if is_verified
+    HrrRbSsh::Authentication::PARTIAL_SUCCESS
+  else
+    false
+  end
+}
+options['authentication_preferred_authentication_methods'] = auth_preferred_authentication_methods
+options['authentication_publickey_authenticator'] = auth_publickey
+options['authentication_password_authenticator'] = auth_password
+```
+
+##### More flexible authentication
+
+A `context` variable in an authenticator gives an access to remaining authentication methods that can continue. In this strategy, an implementer is able to control the order of authentication methods and to control which authentication methods are used for the user.
+
+The below is an example. It is expected that any user must be verified by publickey and then another authentication is requested for the user accordingly.
+
+```ruby
+auth_preferred_authentication_methods = ['none']
+auth_none = HrrRbSsh::Authentication::Authenticator.new{ |context|
+  context.authentication_methods.push 'publickey'
+  HrrRbSsh::Authentication::PARTIAL_SUCCESS
+}
+auth_publickey = HrrRbSsh::Authentication::Authenticator.new{ |context|
+  if some_verification(context)
+    case context.username
+    when 'user1'
+      context.authentiation_methods.push 'keyboard-interactive'
+      HrrRbSsh::Authentication::PARTIAL_SUCCESS
+    else
+      false
+    end
+  else
+    false
+  end
+}
+auth_keyboard_interactive = HrrRbSsh::Authentication::Authenticator.new{ |context|
+  if some_verification(context)
+    true # or HrrRbSsh::Authentication::PARTIAL_SUCCESS; both will accept the user because remaining authentication method is only 'keyboard-interactive' in this case
+  else
+    false
+  end
+}
+options['authentication_preferred_authentication_methods'] = auth_preferred_authentication_methods
+options['authentication_none_authenticator'] = auth_none
+options['authentication_publickey_authenticator'] = auth_publickey
+options['authentication_keyboard_interactive_authenticator'] = auth_keyboard_interactive
+```
+
 #### Handling session channel requests
 
 By default, any channel requests belonging to session channel are implicitly ignored. To handle the requests, defining request handlers are required.
@@ -277,6 +371,8 @@ In `HrrRbSsh::Connection::RequestHandler.new` block, context variable basically
 - `#io => [in, out, err]` : `in` is readable and read data is sent by remote. `out` and `err` are writable. `out` is for standard output and written data is sent as channel data. `err` is for standard error and written data is sent as channel extended data.
 - `#chain_proc => {|chain| ... }` : When a session channel is opened, a background thread is started and is waitng for a chained block registered. This `#chain_proc` is used to define how to handle subsequent communications between local and remote. The `chain` variable provides `#call_next` method. In `#proc_chain` block, it is possible to call subsequent block that is defined in another request handler. For instance, shell request must called after pty-req request. The `chain` in pty-req request handler's `#chain_proc` calls `#next_proc` and then subsequent shell request handler's `#chain_proc` will be called.
 - `#close_session` : In most cases, input and output between a client and the server is handled in `#chain_proc` and closing the `#chain_proc` block will lead closing the underlying session channel. This means that to close the underlying session channel it is required to write at least one `#chain_proc` block. If it is not required to use `#chain_proc` block or is required to close the underlying session channel from outside of `#chain_proc` block, `#close_session` can be used. The `#close_session` will close the background thread that calls `#chain_proc` blocks.
+- `#variables => Hash` : A hash instance that is passed from authenticator and is shared in subsequent session channel request handlers
+- `#vars` : The same object that `#variables` returns
 
 And request handler's `context` variable also provides additional methods based on request type. See `lib/hrr_rb_ssh/connection/channel/channel_type/session/request_type/<request type>/context.rb`.
 
@@ -303,9 +399,9 @@ p HrrRbSsh::Transport::EncryptionAlgorithm.list_preferred
 # => ["aes128-ctr", "aes192-ctr", "aes256-ctr", "aes128-cbc", "3des-cbc", "blowfish-cbc", "cast128-cbc", "aes192-cbc", "aes256-cbc", "arcfour"]
 
 p HrrRbSsh::Transport::ServerHostKeyAlgorithm.list_supported
-# => ["ssh-dss", "ssh-rsa", "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521", "ssh-ed25519"]
+# => ["ssh-dss", "ssh-rsa", "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521"]
 p HrrRbSsh::Transport::ServerHostKeyAlgorithm.list_preferred
-# => ["ssh-ed25519", "ecdsa-sha2-nistp521", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp256", "ssh-rsa", "ssh-dss"]
+# => ["ecdsa-sha2-nistp521", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp256", "ssh-rsa", "ssh-dss"]
 
 p HrrRbSsh::Transport::KexAlgorithm.list_supported
 # => ["diffie-hellman-group1-sha1", "diffie-hellman-group14-sha1", "diffie-hellman-group-exchange-sha1", "diffie-hellman-group-exchange-sha256", "diffie-hellman-group14-sha256", "diffie-hellman-group15-sha512", "diffie-hellman-group16-sha512", "diffie-hellman-group17-sha512", "diffie-hellman-group18-sha512", "ecdh-sha2-nistp256", "ecdh-sha2-nistp384", "ecdh-sha2-nistp521"]
@@ -340,9 +436,77 @@ options['local_version'] = "SSH-2.0-OpenSSH"
 
 Please note that the beginning of the string must be `SSH-2.0-`. Otherwise SSH 2.0 remote peer cannot continue negotiation with the local peer.
 
+### Writing SSH client (Experimental)
+
+#### Starting SSH connection
+
+The client mode can be started with `HrrRbSsh::Client.start`. The method takes `target` and `options` arguments. The `target` that the SSH client connects to can be one of:
+
+- (IO) An io that is open for input and output
+- (Array) An array of the target host address or host name and its service port number
+- (String) The target host address or host name; in this case the target service port number will be 22
+
+And the `options` contains various parameters for the SSH connection. At least `username` key must be set in the `options`. Also at least one of `password`, `publickey`, or `keyboard-interactive` needs to be set for authentication instead of authenticators that are used in server mode. Also as similar to server mode, it is possible to specify preferred transport algorithms and preferred authentication methods with the same keywords.
+
+```ruby
+target = ['remotehost', 22]
+options = {
+  username: 'user1',
+  password: 'password1',
+  publickey: ['ssh-rsa', "/home/user1/.ssh/id_rsa")],
+  authentication_preferred_authentication_methods = ['publickey', 'password'],
+}
+HrrRbSsh::Client.start(target, options) do |conn|
+  # Do something here
+  # For instance: conn.exec "command"
+end
+```
+
+#### Executing remote commands
+
+There are some methods supported in client mode. The methods works as a receiver of `conn` block variable.
+
+##### exec method
+
+The `exec` and `exec!` methods execute command on a remote host. Both takes a command argument that is executed in the remote host. And they can take optional `pty` and `env` arguments. When `pty: true` is set, then the command will be executed on a pseudo-TTY. When `env: {'key' => 'value'}` is set, then the environmental variables are set before the command is executed.
+
+The `exec!` method returns `[stdout, stderr]` outputs. Once the command is executed and the outputs are completed, then the method returns the value.
+
+```ruby
+conn.exec! "command" # => [stdout, stderr]
+```
+
+On the other hand, `exec` method takes block like the below example and returns exit status of the command. When the command is executed and the outputs and reading them are finished, then `io_out` and `io_err` return EOF.
+
+```ruby
+conn.exec "command" do |io_in, io_out, io_err|
+  # Do something here
+end
+```
+
+##### shell method
+
+The `shell` method provides a shell access on a remote host. As similar to `exec` method, it takes block and its block variable is also `io_in, io_out, io_err`. `shell` is always on pseudo-TTY, so it doesn't take `pty` optional argument. It takes `env` optional argument. Exiting shell will leads `io_out` and `io_err` EOF.
+
+```ruby
+conn.shell do |io_in, io_out, io_err|
+  # Do something here
+end
+```
+
+##### subsystem method
+
+The `subsystem` method is to start a subsystem on a remote host. The method takes a subsystem name argument and a block. Its block variable is also `io_in, io_out, io_err`. `subsystem` doesn't take `pty` nor `env` optional argument.
+
+```ruby
+conn.subsystem("echo") do |io_in, io_out, io_err|
+  # Do something here
+end
+```
+
 ### Demo
 
-The `demo/server.rb` shows a good example on how to use the hrr_rb_ssh library in SSH server mode.
+The `demo/server.rb` shows a good example on how to use the hrr_rb_ssh library in SSH server mode. And the `demo/client.rb` shows an example on how to use the hrr_rb_ssh library in SSH client mode.
 
 ## Supported Features
 
@@ -367,7 +531,6 @@ The following features are currently supported.
     - ecdsa-sha2-nistp256
     - ecdsa-sha2-nistp384
     - ecdsa-sha2-nistp521
-    - ssh-ed25519
 - Keyboard interactive (generic interactive / challenge response) authentication
 
 ### Transport layer
@@ -390,7 +553,6 @@ The following features are currently supported.
     - ecdsa-sha2-nistp256
     - ecdsa-sha2-nistp384
     - ecdsa-sha2-nistp521
-    - ssh-ed25519
 - Kex algorithm
     - diffie-hellman-group1-sha1
     - diffie-hellman-group14-sha1
@@ -422,7 +584,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/hirura
 
 ## Code of Conduct
 
-Everyone interacting in the HrrRbSsh project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hirura/hrr_rb_ssh/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the HrrRbSsh project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hirura/hrr_rb_ssh/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 

data/demo/client.rb

@@ -0,0 +1,71 @@
+# coding: utf-8
+# vim: et ts=2 sw=2
+
+require 'logger'
+
+begin
+  require 'hrr_rb_ssh'
+rescue LoadError
+  $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+  require 'hrr_rb_ssh'
+end
+
+class MyLoggerFormatter < ::Logger::Formatter
+  def call severity, time, progname, msg
+    "%s, [%s#%d.%x] %5s -- %s: %s\n" % [severity[0..0], format_datetime(time), Process.pid, Thread.current.object_id, severity, progname, msg2str(msg)]
+  end
+end
+
+logger = Logger.new STDOUT
+logger.level = Logger::DEBUG
+logger.formatter = MyLoggerFormatter.new
+
+target = ['localhost', 10022]
+options = {
+  username: 'user1',
+  password: 'password1',
+  publickey: ['ssh-rsa', "/home/user1/.ssh/id_rsa"],
+  keyboard_interactive: [
+    'password1',
+    #'password2' # when keyboard-interactive authentication requires 2nd response
+  ],
+}
+HrrRbSsh::Client.start(target, options, logger: logger){ |conn|
+  puts conn.exec!('ls -l') # => [out, err]
+
+  puts conn.exec!('ls -l', pty: true) # => [out, err] # "ls -l" command will be run on PTY
+
+  conn.exec('ls -l', pty: true){ |io_in, io_out, io_err| # => exit status
+    while true
+      begin
+        print io_out.readpartial(10240)
+      rescue EOFError
+        break
+      end
+    end
+  }
+
+  conn.shell{ |io_in, io_out, io_err| # => exit status
+    t = Thread.new {
+      while true
+        begin
+          print io_out.readpartial(10240)
+        rescue EOFError
+          break
+        end
+      end
+    }
+    io_in.puts "ls -l"
+    io_in.puts "exit"
+    t.join
+  }
+
+  conn.subsystem("echo"){ |io_in, io_out, io_err| # => exit status
+    t = Thread.new {
+      print io_out.readpartial(10240) rescue nil
+    }
+    io_in.puts "string"
+    t.join
+    io_in.close
+  }
+}