net-ssh 0.5.0

data/lib/net/ssh/userauth/userkeys.rb

@@ -0,0 +1,258 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+require 'net/ssh/errors'
+
+module Net
+  module SSH
+    module UserAuth
+
+      # A trivial exception class used to report errors in the key manager.
+      class UserKeyManagerError < Net::SSH::Exception; end
+
+      # This class encapsulates all operations done by clients on a user's
+      # private keys. In practice, the client should never need a reference
+      # to a private key; instead, they grab a list of "identities" (public 
+      # keys) that are available from the UserKeyManager, and then use
+      # the UserKeyManager to do various private key operations using those
+      # identities.
+      #
+      # The UserKeyManager also uses the Agent class to encapsulate the
+      # ssh-agent. Thus, from a client's perspective it is completely
+      # hidden whether an identity comes from the ssh-agent or from a file
+      # on disk.
+      class UserKeyManager
+
+        # The agent factory to use when a new agent instance is needed.
+        attr_writer :agent_factory
+
+        # The key manager instance to use for managing keys
+        attr_writer :keys
+
+        # The logger instance to use for logging messages
+        attr_writer :log
+
+        # The buffer manager to use for providing new buffer instances.
+        attr_writer :buffers
+
+        # The object that will be used to test whether a given key file is
+        # readable. This object must only respond to "readable?" with one
+        # parameter, the file to test the readability of.
+        attr_writer :key_existence_tester
+
+        # The list of user key files that will be examined
+        attr_reader :key_files
+
+        # The list of host key files that will be examined
+        attr_reader :host_key_files
+
+        # Create a new UserKeyManager. By default, the manager will
+        # use the ssh-agent (if it is running).
+        def initialize
+          @key_files = []
+          @host_key_files = []
+          @use_agent = true
+          @agent = nil
+        end
+
+        # Clear all knowledge of any loaded user keys. This also clears the list
+        # of default identity files that are to be loaded, thus making it
+        # appropriate to use if a client wishes to NOT use the default identity
+        # files.
+        def clear!
+          @key_files = []
+          @known_identities = nil
+          self
+        end
+
+        # Clear all knowledge of any loaded host keys. This also clears the list
+        # of default identity files that are to be loaded, thus making it
+        # appropriate to use if a client wishes to NOT use the default identity
+        # files.
+        def clear_host!
+          @host_key_files = []
+          @known_host_identities = nil
+          self
+        end
+
+        # Add the given key_file to the list of key files that will be used.
+        def add( key_file )
+          @key_files.push( key_file ).uniq!
+          self
+        end
+
+        alias :<< :add
+
+        # Add the given key_file to the list of host key files that will be
+        # used.
+        def add_host_key( key_file )
+          @host_key_files.push( key_file ).uniq!
+          self
+        end
+
+        # This is used as a hint to the UserKeyManager indicating that the agent
+        # connection is no longer needed. Any other open resources may be closed
+        # at this time.
+        #
+        # Calling this does NOT indicate that the UserKeyManager will no longer
+        # be used. Identities may still be requested and operations done on
+        # loaded identities, in which case, the agent will be automatically
+        # reconnected. This method simply allows the client connection to be
+        # closed when it will not be used in the immediate future.
+        def finish
+          close_agent
+        end
+
+        # Returns an array of identities (public keys) known to this manager.
+        # The origin of the identities may be from files on disk or from an
+        # ssh-agent. Note that identities from an ssh-agent are always listed
+        # first in the array, with other identities coming after.
+        def identities
+          identities = []
+          @known_identities = Hash.new
+
+          ensure_agent
+          if @agent
+            @agent.identities.each do |key|
+              identities.push key
+              @known_identities[ key ] = { :from => :agent }
+            end
+          end
+
+          @key_files.each do |file|
+            if @key_existence_tester.readable?( file )
+              begin
+                key = @keys.load_public_key( file + ".pub" )
+                identities.push key
+                @known_identities[ key ] = { :from => :file, :file => file }
+              rescue Exception => e
+                @log.warn "could not load public key file " +
+                  "'#{file}.pub' (#{e.message} [#{e.class}])" if @log.warn?
+              end
+            end
+          end
+
+          identities
+        end
+
+        # Returns an array of host identities (public keys) known to this
+        # manager. Host identities are those that identify the current host,
+        # and are used (typically) for hostbased authentication.
+        def host_identities
+          identities = []
+          @known_host_identities = Hash.new
+
+          @host_key_files.each do |file|
+            if @key_existence_tester.readable?( file )
+              begin
+                key = @keys.load_public_key( file + ".pub" )
+                identities.push key
+                @known_host_identities[ key ] =
+                  { :from => :file, :file => file }
+              rescue Exception => e
+                @log.warn "could not load public host key file " +
+                  "'#{file}.pub' (#{e.message} [#{e.class}])" if @log.warn?
+              end
+            end
+          end
+
+          identities
+        end
+
+        # Sign the given data, using the corresponding private key of the given
+        # identity. If the identity was originally obtained from an ssh-agent,
+        # then the ssh-agent will be used to sign the data, otherwise the
+        # private key for the identity will be loaded from disk (if it hasn't
+        # been loaded already) and will then be used to sign the data.
+        #
+        # Regardless of the identity's origin or who does the signing, this
+        # will always return the signature in an SSH2-specified "signature
+        # blob" format.
+        def sign( identity, data )
+          info = find_identity( identity )
+
+          if info[:key].nil? && info[:from] == :file
+            begin
+              info[:key] = @keys.load_private_key( info[:file] )
+            rescue Exception => e 
+              raise UserKeyManagerError,
+                    "the given identity is known, " +
+                    "but the private key could not be loaded " +
+                    "(#{e.message} [#{e.class}])"
+            end
+          end
+
+          if info[:key]
+            sig_blob = @buffers.writer
+            sig_blob.write_string identity.ssh_type
+            sig_blob.write_string info[:key].ssh_do_sign( data.to_s )
+            return sig_blob.to_s
+          end
+
+          if info[:from] == :agent
+            raise UserKeyManagerError,
+              "the agent is no longer available" unless @agent
+            return @agent.sign( identity, data.to_s )
+          end
+
+          raise UserKeyManagerError,
+            "[BUG] can't determine identity origin (#{info.inspect})"
+        end
+
+        # Identifies whether the ssh-agent will be used or not.
+        def use_agent?
+          @use_agent
+        end
+
+        # Toggles whether the ssh-agent will be used or not. If true, an
+        # attempt will be made to use the ssh-agent. If false, any existing
+        # connection to an agent is closed and the agent will not be used.
+        def use_agent=( use_agent )
+          close_agent if !use_agent
+          @use_agent = use_agent
+        end
+
+        # Ensures that a connection to the agent has been made, if an agent is
+        # to be used.
+        def ensure_agent
+          return if @agent || !@use_agent
+          @agent = @agent_factory.open
+        end
+        private :ensure_agent
+
+        # Closes any open connection to an ssh-agent.
+        def close_agent
+          @agent.close if @agent
+          @agent = nil
+        end
+        private :close_agent
+
+        def find_identity( identity )
+          info = @known_identities[ identity ] if @known_identities
+          if !info && @known_host_identities[ identity ]
+            info = @known_host_identities[ identity ]
+          end
+          raise UserKeyManagerError,
+            "the given identity is unknown to the key manager" unless info
+          return info
+        end
+        private :find_identity
+
+      end
+
+    end
+  end
+end

data/lib/net/ssh/util/buffer.rb

@@ -0,0 +1,274 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# All rights reserved.
+#
+# This source file is distributed as part of the Net::SSH Secure Shell Client
+# library for Ruby. This file (and the library as a whole) may be used only as
+# allowed by either the BSD license, or the Ruby license (or, by association
+# with the Ruby license, the GPL). See the "doc" subdirectory of the Net::SSH
+# distribution for the texts of these licenses.
+# -----------------------------------------------------------------------------
+# net-ssh website : http://net-ssh.rubyforge.org
+# project website: http://rubyforge.org/projects/net-ssh
+# =============================================================================
+#++
+
+module Net
+  module SSH
+
+    module Util
+
+      # The abstract ancestor module of both ReaderBufferImpl and
+      # WriterBufferImpl. It defines the common interface for both submodules.
+      module BufferBase
+
+        # exposes the content of the buffer
+        attr_reader :content
+
+        # the length of the buffer's content.
+        def length
+          @content.length
+        end
+
+        # returns a copy of the buffer's content.
+        def to_s
+          ( @content || "" ).dup
+        end
+
+        # Compares the contents of the two buffers.
+        def ==( buffer )
+          to_s == buffer.to_s
+        end
+
+        # Resets the buffer, making it empty.
+        def clear!
+          @content = ""
+        end
+
+        def init_BufferBase( content="" )
+          @content = content
+        end
+        private :init_BufferBase
+
+      end
+
+      # A convenience module for representing a string of encoded data. It
+      # provides an interface for easily reading and decoding the buffer.
+      module ReaderBufferImpl
+
+        # the current position of the pointer in the buffer
+        attr_reader :position
+
+        # used by derived modules and classes to perform any
+        # reader-buffer-specific initialization.
+        def init_ReaderBufferImpl
+          @position = 0
+        end
+        private :init_ReaderBufferImpl
+
+        # Appends the given text to the end of the buffer.
+        def append( text )
+          @content << text
+        end
+
+        # Returns all text from the current pointer to the end of the buffer as
+        # a new buffer as the same class as the receiver.
+        def remainder_as_buffer
+          self.class.new( @content[ @position..-1 ] )
+        end
+
+        # Reads +count+ bytes from the buffer. If +count+ is +nil+, this will
+        # return all remaining text in the buffer. This method will increment
+        # the pointer.
+        def read( count = nil )
+          count = length - @position unless count
+          return nil if @position + count > length
+
+          @position += count
+          @content[ @position-count, count ]
+        end
+
+        # Return the next 8 bytes as a 64-bit integer (in network byte order).
+        def read_int64
+          hi = read_long
+          lo = read_long
+          return ( hi << 32 ) + lo
+        end
+
+        # Return the next four bytes as a long integer (in network byte order).
+        def read_long
+          b = read( 4 ) or return nil
+          b.unpack( "N" ).first
+        end
+
+        # Read the next two bytes as a short integer (in network byte order).
+        def read_short
+          b = read( 2 ) or return nil
+          b.unpack( "n" ).first
+        end
+
+        # Read and return the next byte in the buffer.
+        def read_byte
+          b = read( 1 ) or return nil
+          b[0]
+        end
+
+        # Read and return an SSH2-encoded string. The string starts with a long
+        # integer that describes the number of bytes remaining in the string.
+        def read_string
+          length = read_long or return nil
+          read( length )
+        end
+
+        # Read a single byte and convert it into a boolean, using 'C' rules
+        # (i.e., zero is false, non-zero is true).
+        def read_bool
+          b = read( 1 ) or return nil
+          b[0] != 0
+        end
+
+        # Resets the pointer to the start of the buffer.
+        def reset!
+          @position = 0
+        end
+
+        # Returns true if the pointer is at the end of the buffer.
+        def eof?
+          @position >= length
+        end
+
+        # Resets the buffer, making it empty.
+        def clear!
+          @content = ""
+          @position = 0
+        end
+
+      end # ReaderBufferImpl
+
+      # A convenience module for writing a string of encoded data. It provides
+      # an interface for easily writing and encoding data.
+      module WriterBufferImpl
+
+        def init_WriterBufferImpl
+          # nothing
+        end
+        private :init_WriterBufferImpl
+
+        # Writes the given data literally into the string.
+        def write( *data )
+          @content << data.join
+        end
+
+        # Writes each argument to the buffer as a network-byte-order-encoded
+        # 64-bit integer (8 bytes).
+        def write_int64( *n )
+          n.each do |i|
+            hi = ( i >> 32 ) & 0xFFFFFFFF
+            lo = i & 0xFFFFFFFF
+            @content << [ hi, lo ].pack( "N2" )
+          end
+        end
+
+        # Writes each argument to the buffer as a network-byte-order-encoded
+        # long (4-byte) integer.
+        def write_long( *n )
+          @content << n.pack( "N*" )
+        end
+
+        # Writes each argument to the buffer as a network-byte-order-encoded
+        # short (2-byte) integer.
+        def write_short( *n )
+          @content << n.pack( "n*" )
+        end
+
+        # Writes each argument to the buffer as a byte.
+        def write_byte( *n )
+          @content << n.map { |c| c.chr }.join
+        end
+
+        # Writes each argument to the buffer as an SSH2-encoded string. Each
+        # string is prefixed by its length, encoded as a 4-byte long integer.
+        def write_string( *text )
+          text.each do |string|
+            write_long( string.length )
+            write( string )
+          end
+        end
+
+        # Writes each argument to the buffer as a (C-style) boolean, with 1
+        # meaning true, and 0 meaning false.
+        def write_bool( *b )
+          @content << b.map { |v| ( v ? 1 : 0 ).chr }.join
+        end
+
+        # Writes each argument to the buffer as a bignum (SSH2-style). No
+        # checking is done to ensure that the arguments are, in fact, bignums.
+        def write_bignum( *n )
+          @content << n.map { |b| b.to_ssh }.join
+        end
+
+        # Writes the given arguments to the buffer as SSH2-encoded keys.
+        def write_key( *key )
+          key.each do |k|
+            write_string( k.ssh_type )
+
+            case k.ssh_type
+              when "ssh-dss"
+                write_bignum( k.p )
+                write_bignum( k.q )
+                write_bignum( k.g )
+                write_bignum( k.pub_key )
+
+              when "ssh-rsa"
+                write_bignum( k.e )
+                write_bignum( k.n )
+
+              else
+                raise NotImplementedError,
+                  "unsupported key type '#{k.ssh_type}'"
+            end
+          end
+        end
+
+      end # class WriterBufferImpl
+
+      # A convenience class for a read-only buffer.
+      class ReaderBuffer
+        include BufferBase
+        include ReaderBufferImpl
+
+        def initialize( content )
+          init_BufferBase( content )
+          init_ReaderBufferImpl
+        end
+      end
+
+      # A convenience class for a write-only buffer.
+      class WriterBuffer
+        include BufferBase
+        include WriterBufferImpl
+
+        def initialize( content="" )
+          init_BufferBase( content )
+          init_WriterBufferImpl
+        end
+      end
+
+      # A convenience class for a read/write buffer.
+      class Buffer
+        include BufferBase
+        include ReaderBufferImpl
+        include WriterBufferImpl
+
+        def initialize( content="" )
+          init_BufferBase( content )
+          init_ReaderBufferImpl
+          init_WriterBufferImpl
+        end
+      end
+
+    end # module Util
+
+  end # module SSH
+end # module Net