hrr_rb_sftp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 836dd45879b224d1b99e0584fa6dfb374d51ddb77cbd90dbb08c2697aed1e8b4
-  data.tar.gz: 68dccfef0acb49b3576ef35fe500c8669e213d5b732ebdac34d3ab54ebba3953
+  metadata.gz: 6abfc35304fc1fc0475db003dd172814dc2a1e2308f811efdc9e527b8abebfb3
+  data.tar.gz: 38d78a957ea3650ca0942e6425179dec884b9497fa0f8466dd14eaa2daba149e
 SHA512:
-  metadata.gz: cf36e84da8b26837ad259906b8d6340ed1cfc5e7e0ed3c88c1bd93555d8ab9964321504d40971b26e8cfae48808492389964bf5ffc706bbd4012c1adee1749ff
-  data.tar.gz: 87ef0bfbefdfc259747eecfce36cf7bcef3a07729380b1c827907f62cc64fe5b1065092f5ab65f41622b64afba0dac7744c73d6a69f4410001e65af64159b7c0
+  metadata.gz: '082c34d8f7976f2a5443d5a93782c3265541f43e894afaf93ae7230ab9f6d6ef010323752aa83d66ea62c30f53c1df5d1adc9e1e7ab826dad285461dabf65817'
+  data.tar.gz: 87e00e812bf6bea182e6641860cd7a2422f1d7c333881df826e686a570756ee4653d2d51a663383ee027100303e0ea0c78aa251ca9316a2a024e566086fa36ab

data/README.md

@@ -13,6 +13,8 @@ hrr_rb_sftp can be run on SSH 2.0 server like OpenSSH or [hrr_rb_ssh](https://gi
 - [Usage](#usage)
     - [hrr\_rb\_ssh's SFTP subsystem](#hrr_rb_sshs-sftp-subsystem)
     - [OpenSSH's SFTP subsystem](#opensshs-sftp-subsystem)
+- [Note](#note)
+- [Supported extensions](#supported-extensions)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -115,6 +117,27 @@ hrr_rb_sftp can be an alternative with replacing the line in the config file. (A
 
 Where, the /path/to/hrr_rb_sftp_server.rb code is the same as shown above.
 
+## Note
+
+- Reversal of SSH_FXP_SYMLINK arguments  
+  Because OpenSSH's sftp-server implementation takes SSH_FXP_SYMLINK request linkpath and targetpath arguments in reverse order, this library follows it.  
+  The SSH_FXP_SYMLINK request format is as follows:  
+
+  ```
+  uint32          id
+  string          targetpath
+  string          linkpath
+  ```
+
+## Supported extensions
+
+The following extensions are supported.
+
+- hardlink@openssh.com version 1
+- fsync@openssh.com version 1
+- posix-rename@openssh.com version 1
+- lsetstat@openssh.com version 1
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/hrr_rb_sftp.rb

@@ -1,7 +1,85 @@
+#
+# hrr_rb_sftp is a pure Ruby SFTP server implementation.
+# hrr_rb_sftp now supports SFTP protocol version 1, 2, and 3.
+# hrr_rb_sftp can be run on SSH 2.0 server like OpenSSH or hrr_rb_ssh.
+#
+# It is straightforward to implement SFTP server on SSH 2.0 server library written in Ruby like hrr_rb_ssh.
+# There are two ways to work with hrr_rb_ssh, on same process or spawning child process.
+# On both cases, hrr_rb_ssh's request handler mechanism is used.
+#
+# To run hrr_rb_sftp server on the same process that hrr_rb_ssh is running, instantiate and start the hrr_rb_sftp server in a sftp subsystem request.
+# On the other hand, because the arguments for the hrr_rb_sftp server can be standard input, output, and error, so hrr_rb_sftp can be a independent program and be spawned as a child process.
+#
+# OpenSSH has capability to run user-defined subsystems. Subsystems that the OpenSSH server recognizes are listed in /etc/ssh/sshd_config file.
+# Usually SFTP subsystem is defined by default to use OpenSSH's SFTP server implementation.
+# hrr_rb_sftp can be an alternative with replacing the line in the config file. (After editing the config, reloading or restarting sshd is required.)
+#
+# The following extensions are supported.
+#   - hardlink@openssh.com
+#   - fsync@openssh.com
+#   - posix-rename@openssh.com
+#   - lsetstat@openssh.com
+#
+# @note
+#   - Reversal of SSH_FXP_SYMLINK arguments  
+#     Because OpenSSH's sftp-server implementation takes SSH_FXP_SYMLINK request linkpath and targetpath arguments in reverse order, this library follows it.  
+#     The SSH_FXP_SYMLINK request format is as follows:  
+# 
+#       uint32          id
+#       string          targetpath
+#       string          linkpath
+#
+# @example On the same process that hrr_rb_ssh is running
+#   subsys = HrrRbSsh::Connection::RequestHandler.new { |ctx|
+#     ctx.chain_proc { |chain|
+#       case ctx.subsystem_name
+#       when 'sftp'
+#         begin
+#           sftp_server = HrrRbSftp::Server.new(logger: nil)
+#           sftp_server.start(ctx.io[0], ctx.io[1], ctx.io[2])
+#           exitstatus = 0
+#         rescue
+#           exitstatus = 1
+#         end
+#       else
+#         # Do something for other subsystem, or just return exitstatus
+#         exitstatus = 0
+#       end
+#       exitstatus
+#     }
+#   }
+#   options['connection_channel_request_subsystem']  = subsys
+#
+# @example Spawnning SFTP server process
+#   subsys = HrrRbSsh::Connection::RequestHandler.new { |ctx|
+#     ctx.chain_proc { |chain|
+#       case ctx.subsystem_name
+#       when 'sftp'
+#         pid = spawn("/path/to/hrr_rb_sftp_server.rb", {in: ctx.io[0], out: ctx.io[1], err: ctx.io[2]})
+#         exitstatus = Process.waitpid(pid).to_i
+#       else
+#         # Do something for other subsystem, or just return exitstatus
+#         exitstatus = 0
+#       end
+#       exitstatus
+#     }
+#   }
+#   options['connection_channel_request_subsystem']  = subsys
+#
+# @example hrr_rb_sftp_server.rb
+#   #!/usr/bin/env ruby
+#   require "hrr_rb_sftp"
+#   server = HrrRbSftp::Server.new(logger: nil)
+#   server.start($stdin, $stdout, $stderr)
+#
+# @example Replacing OpenSSH's sftp-server
+#   $ cat /etc/ssh/sshd_config | grep Subsystem
+#   #Subsystem  sftp    /usr/lib/openssh/sftp-server    # Comment out the original line
+#   Subsystem   sftp    /path/to/hrr_rb_sftp_server.rb
+#
 module HrrRbSftp
 end
 
-require "fileutils"
 require "stringio"
 require "etc"
 

data/lib/hrr_rb_sftp/loggable.rb

@@ -1,31 +1,65 @@
 module HrrRbSftp
+
+  #
+  # This module is used to log message with useful logging key.
+  #
+  # @example
+  #   class SomeClass
+  #     include HrrRbSftp::Loggable
+  #     def initialize logger
+  #       self.logger = logger
+  #     end
+  #     def log_some_info
+  #       log_info { "something" }
+  #     end
+  #   end
+  #
   module Loggable
+
+    #
+    # A logger instance that has #fatal, #error, #warn, #info, and #debug methods.
+    #
     attr_accessor :logger
 
+    #
+    # Outputs fatal message when the logger's log level fatal or higher.
+    #
     def log_fatal
       if logger
         logger.fatal(log_key){ yield }
       end
     end
 
+    #
+    # Outputs error message when the logger's log level error or higher.
+    #
     def log_error
       if logger
         logger.error(log_key){ yield }
       end
     end
 
+    #
+    # Outputs warn message when the logger's log level warn or higher.
+    #
     def log_warn
       if logger
         logger.warn(log_key){ yield }
       end
     end
 
+    #
+    # Outputs info message when the logger's log level info or higher.
+    #
     def log_info
       if logger
         logger.info(log_key){ yield }
       end
     end
 
+    #
+    # Outputs debug message when the logger's log level debug or higher.
+    #
     def log_debug
       if logger
         logger.debug(log_key){ yield }

data/lib/hrr_rb_sftp/protocol.rb

@@ -1,56 +1,62 @@
 module HrrRbSftp
+
+  #
+  # This class implements SFTP protocol operations.
+  #
   class Protocol
     include Loggable
 
+    #
+    # @return [Array] A list of SFTP protocol versions that the library supports.
+    #
     def self.versions
       constants.select{|c| c.to_s.start_with?("Version")}.map{|c| const_get(c)}.map{|klass| klass::PROTOCOL_VERSION}
     end
 
+    #
+    # @return [Array] A list of extension-pair that the library supports.
+    #
+    def self.extension_pairs version
+      version_class = const_get(:"Version#{version}")
+      if version_class.const_defined?(:Extensions)
+        version_class::Extensions.extension_pairs
+      else
+        []
+      end
+    end
+
+    #
+    # @param version [Integer] Protocol version.
+    # @param logger [Logger] Logger.
+    #
     def initialize version, logger: nil
       self.logger = logger
 
-      @handles = Hash.new
-      @version = version
-      @version_class = self.class.const_get(:"Version#{@version}")
-      packet_classes = @version_class::Packet.constants.select{|c| c.to_s.start_with?("SSH_FXP_")}.map{|c| @version_class::Packet.const_get(c)}
-      @packets = packet_classes.map{|pkt| [pkt::TYPE, pkt.new(@handles, logger: logger)]}.inject(Hash.new){|h,(k,v)| h.update({k => v})}
+      @context = Hash.new
+      @context[:version] = version
+      @context[:handles] = Hash.new
+      @packets = self.class.const_get(:"Version#{version}")::Packets.new(@context, logger: logger)
     end
 
+    #
+    # Responds to a request.
+    #
+    # @param request_payload [String] Request payload.
+    # @return [String] Response payload that is encoded packet generated by each SFTP protocol version and each request responder.
+    #
     def respond_to request_payload
-      request_type = request_payload[0].unpack("C")[0]
-      response_packet = if @packets.has_key?(request_type)
-                          begin
-                            request_packet = @packets[request_type].decode request_payload
-                          rescue => e
-                            {
-                              :"type"          => @version_class::Packet::SSH_FXP_STATUS::TYPE,
-                              :"request-id"    => (request_payload[1,4].unpack("N")[0] || 0),
-                              :"code"          => @version_class::Packet::SSH_FXP_STATUS::SSH_FX_BAD_MESSAGE,
-                              :"error message" => e.message,
-                              :"language tag"  => "",
-                            }
-                          else
-                            @packets[request_type].respond_to request_packet
-                          end
-                        else
-                          {
-                            :"type"          => @version_class::Packet::SSH_FXP_STATUS::TYPE,
-                            :"request-id"    => (request_payload[1,4].unpack("N")[0] || 0),
-                            :"code"          => @version_class::Packet::SSH_FXP_STATUS::SSH_FX_OP_UNSUPPORTED,
-                            :"error message" => "Unsupported type: #{request_type}",
-                            :"language tag"  => "",
-                          }
-                        end
-      response_type = response_packet[:"type"]
-      @packets[response_type].encode response_packet
+      @packets.respond_to request_payload
     end
 
+    #
+    # Closes opened and not closed handles.
+    #
     def close_handles
       log_info { "closing handles" }
-      @handles.each do |k, v|
+      @context[:handles].each do |k, v|
         v.close rescue nil
       end
-      @handles.clear
+      @context[:handles].clear
       log_info { "handles closed" }
     end
   end

data/lib/hrr_rb_sftp/protocol/common.rb

@@ -1,10 +1,13 @@
 module HrrRbSftp
   class Protocol
+
+    #
+    # This module implements SFTP protocol version independent common functions.
+    #
     module Common
     end
   end
 end
 
-require "hrr_rb_sftp/protocol/common/data_type"
-require "hrr_rb_sftp/protocol/common/packetable"
-require "hrr_rb_sftp/protocol/common/packet"
+require "hrr_rb_sftp/protocol/common/data_types"
+require "hrr_rb_sftp/protocol/common/packets"

data/lib/hrr_rb_sftp/protocol/common/data_types.rb

@@ -0,0 +1,19 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+
+      #
+      # This module implements SFTP protocol version common data types to be used to encode or decode packet.
+      #
+      module DataTypes
+      end
+    end
+  end
+end
+
+require "hrr_rb_sftp/protocol/common/data_types/byte"
+require "hrr_rb_sftp/protocol/common/data_types/uint32"
+require "hrr_rb_sftp/protocol/common/data_types/uint64"
+require 'hrr_rb_sftp/protocol/common/data_types/string'
+require 'hrr_rb_sftp/protocol/common/data_types/extension_pair'
+require 'hrr_rb_sftp/protocol/common/data_types/extension_pairs'

data/lib/hrr_rb_sftp/protocol/common/data_types/byte.rb

@@ -0,0 +1,40 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module DataTypes
+
+        #
+        # This module provides methods to convert ::Integer value and 8-bit unsigned binary string each other.
+        #
+        module Byte
+
+          #
+          # Convert ::Integer value into 8-bit unsigned binary string.
+          #
+          # @param arg [::Integer] ::Integer value to be converted.
+          # @raise [::ArgumentError] When arg is not between 0x00 and 0xff.
+          # @return [::String] Converted 8-bit unsigned binary string.
+          #
+          def self.encode arg
+            case arg
+            when 0x00..0xff
+              [arg].pack("C")
+            else
+              raise ArgumentError, "must be in #{0x00}..#{0xff}, but got #{arg.inspect}"
+            end
+          end
+
+          #
+          # Convert 8-bit unsigned binary into ::Integer value.
+          #
+          # @param io [::IO] ::IO instance that has buffer to be read.
+          # @return [::Integer] Converted ::Integer value.
+          #
+          def self.decode io
+            io.read(1).unpack("C")[0]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/common/data_types/extension_pair.rb

@@ -0,0 +1,41 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module DataTypes
+
+        #
+        # This module provides methods to convert extension-name and extension-data pair represented in ::Hash and binary string each other.
+        #
+        module ExtensionPair
+
+          #
+          # Convert extension-name and extension-data pair represented in ::Hash into binary string.
+          #
+          # @param arg [::Hash{::Symbol=>::String}] Extension-name and extension-data pair represented in ::Hash to be converted.
+          # @raise [::ArgumentError] When arg is not ::Hash value.
+          # @return [::String] Converted binary string.
+          #
+          def self.encode arg
+            unless arg.kind_of? ::Hash
+              raise ArgumentError, "must be a kind of Hash, but got #{arg.inspect}"
+            end
+            DataTypes::String.encode(arg[:"extension-name"]) + DataTypes::String.encode(arg[:"extension-data"])
+          end
+
+          #
+          # Convert binary string into extension-name and extension-data pair represented in ::Hash.
+          #
+          # @param io [::IO] ::IO instance that has buffer to be read.
+          # @return [::Hash{::Symbol=>::String}] Converted extension-name and extension-data pair represented in ::Hash.
+          #
+          def self.decode io
+            {
+              :"extension-name" => DataTypes::String.decode(io),
+              :"extension-data" => DataTypes::String.decode(io),
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hrr_rb_sftp/protocol/common/data_types/extension_pairs.rb

@@ -0,0 +1,42 @@
+module HrrRbSftp
+  class Protocol
+    module Common
+      module DataTypes
+
+        #
+        # This module provides methods to convert list of extension-name and extension-data pair represented in ::Array and binary string each other.
+        #
+        module ExtensionPairs
+
+          #
+          # Convert list of extension-name and extension-data pair represented in ::Array into binary string.
+          #
+          # @param arg [::Array<::Hash{::Symbol=>::String}>] List of extension-name and extension-data pair represented in ::Array to be converted.
+          # @raise [::ArgumentError] When arg is not ::Array value.
+          # @return [::String] Converted binary string.
+          #
+          def self.encode arg
+            unless arg.kind_of? ::Array
+              raise ArgumentError, "must be a kind of Array, but got #{arg.inspect}"
+            end
+            arg.map{|arg| ExtensionPair.encode(arg)}.join
+          end
+
+          #
+          # Convert binary string into list of extension-name and extension-data pair represented in ::Array.
+          #
+          # @param io [::IO] ::IO instance that has buffer to be read.
+          # @return [::Array<::Hash{::Symbol=>::String}>] Converted list of extension-name and extension-data pair represented in ::Array.
+          #
+          def self.decode io
+            extension_pairs = Array.new
+            until io.eof?
+              extension_pairs.push ExtensionPair.decode(io)
+            end
+            extension_pairs
+          end
+        end
+      end
+    end
+  end
+end