octokey 0.1.pre.2 → 0.1.pre.3

data/lib/octokey/auth_request.rb

@@ -0,0 +1,210 @@
+class Octokey
+  # An AuthRequest is sent by the client when it wants to log in or sign up.
+  #
+  # It includes an {Octokey::Challenge} so that we can verify its recency, and
+  # also the username the user wishes to log in as, the url that they wish to 
+  # log in to, and the public key corresponding to their private key.
+  #
+  # You can create an Octokey::AuthRequest from any string, and later determine
+  # whether or not it was valid by calling {#valid?}
+  class AuthRequest
+    # The service name is used to check that the client knows which protocol it is speaking.
+    SERVICE_NAME      = "octokey-auth"
+    # The auth method indicates that the client wants to use publickey authentication.
+    AUTH_METHOD       = "publickey"
+    # The signing algorithm is copied straight from SSH.
+    SIGNING_ALGORITHM = "ssh-rsa"
+
+    attr_accessor :challenge_buffer, :request_url, :username, :service_name,
+                  :auth_method, :signing_algorithm, :public_key, :signature_buffer,
+                  :invalid_buffer
+
+    # Given a challenge and a private key, generate an auth request.
+    #
+    # @param [Hash] opts
+    # @option opts [String] :request_url
+    # @option opts [String] :username
+    # @option opts [String] :challenge  The base64-encoded challenge
+    # @option opts [OpenSSL::PKey::RSA] :private_key
+    # @return [Octokey::AuthRequest]
+    def self.generate(opts)
+      private_key = opts[:private_key] or raise ArgumentError, "No private_key given"
+      challenge = opts[:challenge] or raise ArgumentError, "No challenge given"
+
+      new.instance_eval do
+        self.challenge_buffer = Octokey::Buffer.new(challenge)
+        self.request_url = opts[:request_url] or raise ArgumentError, "No request_url given"
+        self.username = opts[:username] or raise ArgumentError, "No username given"
+        self.service_name = SERVICE_NAME
+        self.auth_method = AUTH_METHOD
+        self.signing_algorithm = SIGNING_ALGORITHM
+        self.public_key = Octokey::PublicKey.from_key(private_key.public_key)
+        self.signature_buffer = signature_buffer_with(private_key)
+
+        self
+      end
+    end
+
+    # Parse an auth request sent from the client.
+    #
+    # @param[String]  The base64-encoded auth request from the client.
+    # @return [Octokey::AuthRequest]
+    def self.from_string(string)
+      buffer = Octokey::Buffer.new(string)
+      new.instance_eval do
+        begin
+          self.challenge_buffer, self.request_url, self.username,
+          self.service_name, self.auth_method, self.signing_algorithm,
+          self.public_key, self.signature_buffer =
+            buffer.scan_all(
+              :buffer, :string, :string,
+              :string, :string, :string,
+              :public_key, :buffer)
+        rescue Octokey::InvalidBuffer => e
+          self.invalid_buffer = e.message
+        end
+
+        self
+      end
+    end
+
+    # Get any errors ignoring those caused by the challenge.
+    #
+    # @param [Hash] opts
+    # @return [Array<String>]
+    def errors_ignoring_challenge(opts)
+      return [invalid_buffer] if invalid_buffer
+      errors = []
+
+      errors += request_url_errors(opts)
+      errors << "Auth request username mismatch"             unless username == opts[:username]
+      errors << "Auth request service name mismatch"         unless service_name == SERVICE_NAME
+      errors << "Auth request auth method unsupported"       unless auth_method == AUTH_METHOD
+      errors << "Auth request signing algorithm unsupported" unless signing_algorithm == SIGNING_ALGORITHM
+
+      if public_key.valid?
+        errors += signature_errors(public_key.public_key, signature_buffer.dup)
+      else
+        errors += public_key.errors
+      end
+
+      errors
+    end
+
+    # Get any errors caused by the challenge. 
+    #
+    # @param [Hash] opts
+    # @return [Array<String>]
+    def challenge_errors(opts)
+      return [] if invalid_buffer
+      Octokey::Config.get_challenge(challenge_buffer.to_s, opts).errors(opts)
+    end
+
+    # Get all the error for this auth request.
+    #
+    # @param [Hash] opts
+    # @return [Array<String>]
+    def errors(opts)
+      errors_ignoring_challenge(opts) + challenge_errors(opts)
+    end
+
+    # If the challenge was valid, would this auth request be valid?
+    #
+    # This can be used to check whether the auth request should be retried.
+    #
+    # @param [Hash] opts
+    # @return [Boolean]
+    def valid_ignoring_challenge?(opts)
+      errors_ignoring_challenge(opts) == []
+    end
+
+    # Is this auth request valid?
+    #
+    # @param [Hash] opts
+    # @return [Boolean]
+    def valid?(opts)
+      errors(opts) == []
+    end
+
+    # Get the Base64-encoded version of this auth request.
+    #
+    # @return [String]
+    def to_s
+      unsigned_buffer.add_buffer(signature_buffer).to_s
+    end
+
+    # Get a string that identifies this auth request while debugging
+    #
+    # @return [String]
+    def inspect
+      "#<Octokey::AuthRequest #{to_s.inspect}>"
+    end
+
+    private
+
+    # What are the problems with the signature? 
+    #
+    # @param [OpenSSL::PKey::RSA] key  the public key
+    # @param [Octokey::Buffer] signature_buffer  the signature buffer
+    # @return [Array<String>]
+    def signature_errors(key, signature_buffer)
+      algorithm_used, signature = signature_buffer.scan_all(:string, :varbytes)
+
+      errors = []
+      errors << "Signature type mismatch" unless algorithm_used == signing_algorithm
+      errors << "Signature mismatch"      unless key.verify(OpenSSL::Digest::SHA1.new, signature, unsigned_buffer.raw)
+      errors
+
+    rescue Octokey::InvalidBuffer => e
+      ["Signature #{e.message}"]
+    end
+
+    # What are the problems with the request url?
+    #
+    # @param [Hash] opts
+    # @return [Array<String>]
+    def request_url_errors(opts)
+      url = URI.parse(request_url)
+
+      valid_hostname = Octokey::Config.valid_hostnames.any? do |hostname|
+        if hostname[/\A\*\.(.*)\z/]
+          url.host.end_with?($1)
+        else
+          url.host == hostname
+        end
+      end
+
+      errors = []
+      errors << "Request url insecure" unless url.scheme == "https"
+      errors << "Request url mismatch" unless valid_hostname
+      errors
+
+    rescue URI::InvalidURIError
+      ["Request url invalid"]
+    end
+
+    # Get the buffer containing everything other than the signature.
+    #
+    # @return [Octokey::Buffer]
+    def unsigned_buffer
+      Octokey::Buffer.new.
+        add_buffer(challenge_buffer).
+        add_string(request_url).
+        add_string(username).
+        add_string(service_name).
+        add_string(auth_method).
+        add_string(signing_algorithm).
+        add_public_key(public_key)
+    end
+
+    # Get the signature buffer using the given key.
+    #
+    # @param [OpenSSL::PKey::RSA] private_key
+    # @return [Octokey::Buffer]
+    def signature_buffer_with(private_key)
+      Octokey::Buffer.new.
+        add_string(SIGNING_ALGORITHM).
+        add_varbytes(private_key.sign(OpenSSL::Digest::SHA1.new, unsigned_buffer.raw))
+    end
+  end
+end

data/lib/octokey/buffer.rb

@@ -1,12 +1,24 @@
 require 'base64'
 class Octokey
+  # Buffers are used throughout Octokey to provide a bijective serialization format.
+  # For any valid buffer, there's exactly one valid object, and vice-versa.
+  #
+  # Mostly we used Base64-encoded buffers to avoid problems with potentially 8-bit
+  # unsafe channels. You should take care not to perform any operations on the Base64
+  # encoded form as there are many accepted formats for Base64-encoding a given string.
+  #
+  # In the current implementation, reading out of a buffer is a destructive operation,
+  # you should first .dup any buffer that you want to read more than once.
   class Buffer
-    attr_accessor :buffer, :pos
+    attr_accessor :buffer, :invalid_buffer
 
     # to avoid DOS caused by duplicating enourmous buffers,
     # we limit the maximum size of any string stored to 100k
     MAX_STRING_SIZE = 100 * 1024
 
+    # Create a new buffer from raw bits.
+    #
+    # @param [String] raw
     def self.from_raw(raw = "")
       ret = new
       ret.buffer = raw.dup
@@ -14,95 +26,107 @@ class Octokey
       ret
     end
 
+    # Create a new buffer from a Base64-encoded string.
+    # @param [String] string
     def initialize(string = "")
       self.buffer = Base64.decode64(string || "")
-      self.pos = 0
-      buffer.force_encoding('BINARY') if @buffer.respond_to?(:force_encoding)
+      buffer.force_encoding('BINARY') if buffer.respond_to?(:force_encoding)
+      self.invalid_buffer = "Badly formatted Base64" unless to_s == string
     end
 
+    # Get the underlying bits contained in this buffer.
+    # @return [String]
     def raw
       buffer
     end
-
-    def empty?
-      buffer.empty?
-    end
-
+    
+    # Get the canonical Base64 representation of this buffer.
+    # @return [String]
     def to_s
       Base64.encode64(buffer).gsub("\n", "")
     end
 
-    def <<(bytes)
-      buffer << bytes
+    # Get a string that describes this buffer suitably for debugging.
+    # @return [String]
+    def inspect
+      "#<Octokey::Buffer @buffer=#{to_s.inspect}>"
     end
 
-    def scan(n)
-      ret, buf = [buffer[0...n], buffer[n..-1]]
-      if ret.size < n || !buf
-        raise InvalidBuffer, "Tried to read beyond end of buffer"
-      end
-      self.buffer = buf
-      ret
+    # Is this buffer empty?
+    # @return [Boolean]
+    def empty?
+      buffer.empty?
     end
 
+    # Add an unsigned 8-bit number to this buffer
+    # @param [Fixnum] x
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer] if x is not a uint8
     def add_uint8(x)
       raise InvalidBuffer, "Invalid uint8: #{x}" if x < 0 || x >= 2 ** 8
       buffer << [x].pack("C")
+      self
     end
 
+    # Destructively read an unsigned 8-bit number from this buffer
+    # @return [Fixnum]
+    # @raise [Octokey::InvalidBuffer]
     def scan_uint8
       scan(1).unpack("C").first
     end
 
-    def add_uint32(x)
-      raise InvalidBuffer, "Invalid uint32: #{x}" if x < 0 || x >= 2 ** 32
-      buffer << [x].pack("N")
-    end
-
-    def scan_uint32
-      scan(4).unpack("N").first
-    end
-
-    def add_uint64(x)
-      raise InvalidBuffer, "Invalid uint64: #{x}" if x < 0 || x >= 2 ** 64
-      add_uint32(x >> 32 & 0xffff_ffff)
-      add_uint32(x & 0xffff_ffff)
-    end
-
-    def scan_uint64
-      (scan_uint32 << 32) + scan_uint32
-    end
-
-    def add_uint128(x)
-      raise InvalidBuffer, "Invalid uint128: #{x}" if x < 0 || x >= 2 ** 128
-      add_uint64(x >> 64 & 0xffff_ffff_ffff_ffff)
-      add_uint64(x & 0xffff_ffff_ffff_ffff)
-    end
-
-    def scan_uint128
-      (scan_uint64 << 64) + scan_uint64
-    end
-
+    # Add a timestamp to this buffer
+    #
+    # Times are stored to millisecond precision, and are limited to
+    # 2 **48 to give plenty of margin for implementations using doubles
+    # as the backing for their date time, which nicely gives us a range
+    # ending just after the year 10000.
+    #
+    # @param [Time] time
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer] if the time is too far into the future
     def add_time(time)
-      add_uint64((time.to_f * 1000).to_i)
+      seconds, millis = [time.to_i, (time.usec / 1000.0).round]
+      raw = seconds * 1000 + millis
+      raise Octokey::InvalidBuffer, "Invalid time" if raw >= 2 ** 48
+      add_uint64(raw)
+      self
     end
 
+    # Destructively read a timestamp from this buffer
+    #
+    # Times are stored to millisecond precision
+    #
+    # @return [Time]
+    # @raise [Octokey::InvalidBuffer]
     def scan_time
-      Time.at(scan_uint64.to_f / 1000)
+      raw = scan_uint64
+      raise Octokey::InvalidBuffer, "Invalid time" if raw >= 2 ** 48
+      seconds, millis = [raw / 1000, raw % 1000]
+      Time.at(seconds).utc + (millis / 1000.0)
     end
 
+    # Add an IPv4  or IPv6 address to this buffer
+    #
+    # @param [IPAddr] ipaddr
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer] not a valid IP address
     def add_ip(ipaddr)
       if ipaddr.ipv4?
         add_uint8(4)
-        add_uint32(ipaddr.to_i)
+        buffer << ipaddr.hton
       elsif ipaddr.ipv6?
         add_uint8(6)
-        add_uint128(ipaddr.to_i)
+        buffer << ipaddr.hton
       else
         raise InvalidBuffer, "Unsupported IP address: #{ipaddr.to_s}"
       end
+      self
     end
 
+    # Destructively read an IPv4 or IPv6 address from this buffer.
+    # @return [IPAddr]
+    # @raise [Octokey::InvalidBuffer]
     def scan_ip
       type = scan_uint8
       case type
@@ -111,69 +135,210 @@ class Octokey
       when 6
         IPAddr.new_ntoh scan(16)
       else
-        raise InvalidBuffer, "Unsupported IP address family: #{type}"
+        raise InvalidBuffer, "Unknown IP family: #{type.inspect}"
       end
     end
 
+    # Add a length-prefixed number of bytes to this buffer
+    # @param [String] bytes
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer] if there are too any bytes
     def add_varbytes(bytes)
+      bytes.force_encoding('BINARY') if bytes.respond_to?(:force_encoding)
       size = bytes.size
-      raise InvalidBuffer, "String too long: #{size}" if size > MAX_STRING_SIZE
+      raise InvalidBuffer, "Too much length: #{size}" if size > MAX_STRING_SIZE
       add_uint32 size
-      self << bytes
+      buffer << bytes
+      self
     end
 
+    # Destructively read a length-prefixed number of bytes from this buffer
+    # @return [String] bytes
+    # @raise [Octokey::InvalidBuffer]
     def scan_varbytes
       size = scan_uint32
-      raise InvalidBuffer, "String too long: #{size}" if size > MAX_STRING_SIZE
+      raise InvalidBuffer, "Too much length: #{size}" if size > MAX_STRING_SIZE
       scan(size)
     end
 
+    # Add a length-prefixed number of bytes of UTF-8 string to this buffer
+    # @param [String] string
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer]  if the string is not utf-8
     def add_string(string)
-      if string.respond_to?(:encode)
-        add_varbytes string.encode('BINARY')
-      else
-        add_varbytes string
-      end
+      add_varbytes(validate_utf8(string))
     end
 
+    # Destructively read a length-prefixed number of bytes of UTF-8 string
+    # @return [String] with encoding == 'utf-8' on ruby-1.9
+    # @raise [Octokey::InvalidBuffer]
     def scan_string
-      string = scan_varbytes
-      if string.respond_to?(:encode)
-        string.encode('UTF-8')
-      else
-        string
-      end
-    rescue EncodingError => e
-      raise InvalidBuffer, e
+      validate_utf8(scan_varbytes)
     end
 
+    # Add the length-prefixed contents of another buffer to this one.
+    # @param [Octokey::Buffer] buffer
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer]
     def add_buffer(buffer)
       add_varbytes buffer.raw
+      self
     end
 
+    # Destrictively read a length-prefixed buffer out of this one.
+    # @return [Octokey::Buffer]
+    # @raise [Octokey::InvalidBuffer]
     def scan_buffer
       Octokey::Buffer.from_raw scan_varbytes
     end
 
+    # Add an unsigned multi-precision integer to this buffer
+    # @param [OpenSSL::BN,Fixnum] x
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer] if x is negative or enourmous
     def add_mpint(x)
-      raise InvalidBuffer, "Got negative mpint" if x < 0
+      raise InvalidBuffer, "Invalid mpint: #{mpint.inspect}" if x < 0
       bytes = OpenSSL::BN.new(x.to_s, 10).to_s(2)
       bytes = "\x00" + bytes if bytes.bytes.first >= 0x80
       add_varbytes(bytes)
+      self
     end
 
+    # Destructively read an unsigned multi-precision integer from this buffer
+    # @return [OpenSSL::BN]
+    # @raise [Octokey::InvalidBuffer]
     def scan_mpint
-      bytes = scan_varbytes
+      raw = scan_varbytes
 
-      if bytes.bytes.first >= 0x80
-        raise InvalidBuffer, "Got negative mpint"
+      first, second = raw.bytes.first(2)
+
+      # ensure only positive numbers with no superflous leading 0s
+      if first >= 0x80 || first == 0x00 && second < 0x80
+        raise InvalidBuffer, "Badly formatted mpint"
       end
 
-      OpenSSL::BN.new(bytes, 2)
+      OpenSSL::BN.new(raw, 2)
     end
 
-    def inspect
-      "#<Octokey::Buffer @buffer=#{to_s.inspect}>"
+    # Destructively read a public key from this buffer
+    #
+    # NOTE: the returned public key may not be valid, you must call
+    # .valid? on it before trying to use it.
+    #
+    # @return [Octokey::PublicKey]
+    # @raise [Octokey::InvalidBuffer]
+    def scan_public_key
+      Octokey::PublicKey.from_buffer(scan_buffer)
+    end
+
+    # Add a public key to this buffer
+    # @param [Octokey::PublicKey] public_key
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer]
+    def add_public_key(public_key)
+      add_buffer public_key.to_buffer
+    end
+
+    # Destructively read the entire buffer.
+    #
+    # It's strongly recommended that you use this method to parse buffers, as it
+    # remembers to verify that the buffer doesn't contain any trailing bytes; and
+    # will return nothing if the buffer is invalid, so your code doesn't have to 
+    # deal with half-parsed buffers.
+    #
+    # The tokens should correspond to the scan_X methods defined here. For example:
+    #  type, e, n = buffer.scan_all(:string, :mpint, :mpint)
+    # is equivalent to:
+    #  type, e, n, _ = [buffer.scan_string, buffer.scan_mpint, buffer.scan_mpint,
+    #                   buffer.scan_end]
+    #
+    # @param [Array<Symbol>] tokens
+    # @return [Array<Object>]
+    # @raise [Octokey::InvalidBuffer]
+    def scan_all(*tokens)
+      ret = tokens.map do |token|
+        raise "invalid token type: #{token.inspect}" unless respond_to?("scan_#{token}")
+        send("scan_#{token}")
+      end
+
+      scan_end
+      ret
+    end
+
+    # Verify that the buffer has been completely scanned.
+    # @raise [Octokey::InvalidBuffer] if there is still buffer to read.
+    def scan_end
+      raise InvalidBuffer, "Buffer too long" unless empty?
+    end
+
+    private
+
+    # Destructively read bytes from the front of this buffer.
+    # @param [Fixnum] n
+    # @return [String]
+    # @raise [Octokey::InvalidBuffer]
+    def scan(n)
+      raise InvalidBuffer, invalid_buffer if invalid_buffer
+      ret, buf = [buffer[0...n], buffer[n..-1]]
+      if ret.size < n || !buf
+        raise InvalidBuffer, "Buffer too short"
+      end
+      self.buffer = buf
+      ret
+    end
+
+    # Add an unsigned 32-bit number to this buffer
+    # @param [Fixnum] x
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer] if x is not a uint32
+    def add_uint32(x)
+      raise InvalidBuffer, "Invalid uint32: #{x}" if x < 0 || x >= 2 ** 32
+      buffer << [x].pack("N")
+      self
+    end
+
+    # Destructively read an unsigned 32-bit number from this buffer
+    # @return [Fixnum]
+    # @raise [Octokey::InvalidBuffer]
+    def scan_uint32
+      scan(4).unpack("N").first
+    end
+
+    # Add an unsigned 64-bit number to this buffer
+    # @param [Fixnum] x
+    # @return [Octokey::Buffer] self
+    # @raise [Octokey::InvalidBuffer] if x is not a uint64
+    def add_uint64(x)
+      raise InvalidBuffer, "Invalid uint64: #{x}" if x < 0 || x >= 2 ** 64
+      add_uint32(x >> 32 & 0xffff_ffff)
+      add_uint32(x & 0xffff_ffff)
+      self
+    end
+
+    # Destructively read an unsigned 64-bit number from this buffer
+    # @return [Fixnum]
+    # @raise [Octokey::InvalidBuffer]
+    def scan_uint64
+      (scan_uint32 << 32) + scan_uint32
+    end
+
+    # Check whether a string is valid utf-8
+    # @param [String] string
+    # @return [String] string
+    # @raise [Octokey::InvalidBuffer] invalid utf-8
+    def validate_utf8(string)
+      if string.respond_to?(:force_encoding)
+        string.force_encoding('UTF-8')
+        raise InvalidBuffer, "String not UTF-8" unless string.valid_encoding?
+        string
+      else
+        require 'iconv'
+        begin
+          Iconv.conv('utf-8', 'utf-8', string)
+        rescue Iconv::Failure
+          raise InvalidBuffer, "String not UTF-8"
+        end
+      end
     end
   end
 end