octokey 0.1.pre.2-jruby

data/lib/octokey.rb

@@ -0,0 +1,149 @@
+require 'openssl'
+require 'securerandom'
+require 'ipaddr'
+require 'uri'
+
+require File.expand_path('octokey/buffer', File.dirname(__FILE__))
+require File.expand_path('octokey/config', File.dirname(__FILE__))
+require File.expand_path('octokey/challenge', File.dirname(__FILE__))
+require File.expand_path('octokey/public_key', File.dirname(__FILE__))
+require File.expand_path('octokey/auth_request', File.dirname(__FILE__))
+
+# Octokey is a private key based login mechanism for websites inspired
+# heavily by, and borrowing algorithms from, OpenSSH.
+class Octokey
+  # Raised when you try and access details of an invalid octokey request.
+  # If you always check .can_log_in? or .can_sign_up? first, you should not
+  # see this exception.
+  class InvalidRequest < StandardError; end
+
+  # Raised if an Octokey::Buffer is invalid. This is usually caught by Octokey
+  # so you will only need to catch it if you are parsing buffers yourself.
+  class InvalidBuffer < InvalidRequest; end
+
+  # Create a new challenge.
+  #
+  # Once created, the challenge should be sent to the client for it to sign.
+  #
+  # The client_ip address is included in the outgoing challenge to verify that
+  # incoming login requests came from the same client as requested the challenge.
+  #
+  # @param [Hash] opts
+  # @option opts [String,IPAddr] client_ip  The IP address of the client.
+  # @return [String]  The Base64 encoded challenge.
+  def self.new_challenge(opts)
+    Octokey::Challenge.generate(opts).to_s
+  end
+
+  # Sign a challenge.
+  #
+  # If you're acting as an Octokey client, then you use this function to turn
+  # a challenge that you've been issued into an auth_request to send back to the
+  # server.
+  #
+  # @param [String] challenge  The base64-encoded challenge issued by the server.
+  # @param [Hash] opts
+  # @option opts [String] :username  Which username would you like to log in as.
+  # @option opts [String] :request_url  Which page would you like to log in to.
+  # @option opts [OpenSSL::PKey::RSA] :private_key  The private key with which to sign the challenge.
+  # @return [String]  The Base64 encoded auth_request
+  def self.sign_challenge(challenge, opts)
+    Octokey::AuthRequest.generate({:challenge => challenge}.merge(opts)).to_s
+  end
+
+  # Handle a new Octokey request.
+  #
+  # The options passed in to this method will be passed in as the second parameter to
+  # all the configuration blocks.
+  #
+  # @param [String] auth_request  The Base64 encoded auth request from the client.
+  # @param [Hash] opts
+  # @option opts [String] :username  The username that the user wishes to log in as.
+  # @option opts [String,IPAddr] :client_ip  The ip address of the client.
+  def initialize(auth_request, opts)
+    raise ArgumentError, "no :username given" unless opts[:username]
+    raise ArgumentError, "no :client_ip given" unless opts[:client_ip]
+    @opts = opts.dup
+    @auth_request = Octokey::Config.get_auth_request(auth_request, opts)
+  end
+
+  # Should the user be allowed to log in?
+  #
+  # If this method returns true then you can assume that the user with :username
+  # is actually the user who's trying to log in.
+  #
+  # @return [Boolean]
+  def can_log_in?
+    valid_auth_request? && valid_public_key?
+  end
+
+  # Should the user be allowed to sign up?
+  #
+  # If this method returns true then you can store the public_key against the
+  # user's username. Future logins by that user will use that to verify that the user
+  # trying to log in has access to the private key that corresponds to this public key.
+  #
+  # @return [Boolean]
+  def can_sign_up?
+    valid_auth_request?
+  end
+
+  # Was the failure to log in or sign up transient?
+  #
+  # This will return true if the client may be able to log in simply by requesting
+  # a new challenge from the server and retrying the auth_request.
+  #
+  # @return [Boolean]
+  def should_retry?
+    !valid_auth_request? && auth_request.valid_ignoring_challenge?(opts)
+  end
+
+  # Get the username used for this request.
+  #
+  # You must validate that the username meets your requirements for a valid username,
+  # Octokey allows any username (for example the empty string, the string "\r\n"). You might
+  # want to enforce that the username is an email address, or contains only visible characters.
+  #
+  # @return [String] username
+  # @raise [InvalidRequest] if neither .can_sign_up? nor .can_log_in?
+  def username
+    raise InvalidRequest, "Tried to get username from invalid octokey" unless valid_auth_request?
+    auth_request.username
+  end
+
+  # Get the public_key used for this request.
+  #
+  # You will need this when handling a sign up request for the user in order to
+  # extract the public key needed to log in.
+  #
+  # The format of the returned public key is exactly the same as used by SSH in the
+  # ~/.authorized_keys file. That format can be parsed by {Octokey::PublicKey} if you
+  # need more information.
+  #
+  # @return [String]
+  # @raise [InvalidRequest] if neither .can_sign_up? nor .can_log_in?
+  def public_key
+    raise InvalidRequest, "Tried to get username from invalid octokey" unless valid_auth_request?
+    auth_request.public_key.to_s
+  end
+
+  private
+  attr_accessor :opts, :auth_request
+
+  # Is the auth_request valid?
+  # @return [Boolean]
+  def valid_auth_request?
+    @valid ||= auth_request.valid?(opts)
+  end
+
+  # Is the public key used to sign the auth request one of those that belongs to the username?
+  # @return [Boolean]
+  def valid_public_key?
+    strings = Octokey::Config.get_public_keys(opts[:username], opts)
+    public_keys = strings.map{ |string| Octokey::PublicKey.from_string(string) }
+    unless public_keys.all?(&:valid?)
+      raise ArgumentError, "Invalid public key returned to Octokey for #{username}"
+    end
+    public_keys.include?(auth_request.public_key)
+  end
+end

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

@@ -0,0 +1,344 @@
+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, :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
+      ret.buffer.force_encoding('BINARY') if ret.buffer.respond_to?(:force_encoding)
+      ret
+    end
+
+    # Create a new buffer from a Base64-encoded string.
+    # @param [String] string
+    def initialize(string = "")
+      self.buffer = Base64.decode64(string || "")
+      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
+    
+    # Get the canonical Base64 representation of this buffer.
+    # @return [String]
+    def to_s
+      Base64.encode64(buffer).gsub("\n", "")
+    end
+
+    # Get a string that describes this buffer suitably for debugging.
+    # @return [String]
+    def inspect
+      "#<Octokey::Buffer @buffer=#{to_s.inspect}>"
+    end
+
+    # 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
+
+    # 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)
+      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
+      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)
+        buffer << ipaddr.hton
+      elsif ipaddr.ipv6?
+        add_uint8(6)
+        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
+      when 4
+        IPAddr.new_ntoh scan(4)
+      when 6
+        IPAddr.new_ntoh scan(16)
+      else
+        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, "Too much length: #{size}" if size > MAX_STRING_SIZE
+      add_uint32 size
+      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, "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)
+      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
+      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, "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
+      raw = scan_varbytes
+
+      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(raw, 2)
+    end
+
+    # 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

data/lib/octokey/challenge.rb

@@ -0,0 +1,178 @@
+class Octokey
+  # In order to verify that the client is in posession of the private key that
+  # corresponds to the public key that it claims to own, we need to give it a
+  # string to sign.
+  #
+  # In order for the scheme to be as secure as possible, the challenges should
+  # be unique, unguessable and unforgeable. This prevents an attacker who can
+  # somehow generate valid signatures from being able to pre-compute any.
+  #
+  # Additionally, challenges should expire after a short time. This both makes
+  # it harder for the attacker that can generate valid signatures (they have to
+  # do it quickly), and also protects users in case logs of signed auth requests
+  # are "leaked" as the attackers will not be able to re-use any of them.
+  #
+  # The client_ip is included in the challenge to make it harder for attackers
+  # who can read logs in real-time to use challenges; they'd have to be able to
+  # forge their IP address too. This doesn't provide any protection against a
+  # full man-in-the-middle attack, because such an attacker could likely forge
+  # the client ip address anyway.
+  #
+  # If you're willing to trade architectural simplicity for extra security, you
+  # should consider using a database to store issued challenges and marking them
+  # as "invalid" as soon as they are first attempted. This helps further with
+  # the attacks mentioned above.
+  #
+  class Challenge
+    # Which version of challenges is supported.
+    CHALLENGE_VERSION = 3
+    # How many bytes of random data should be included.
+    RANDOM_SIZE = 32
+    # Hash algorithm to use in the HMAC
+    HMAC_ALGORITHM = "sha1"
+    # The maximum age of a valid challenge
+    MAX_AGE = 5 * 60
+    # The minimum age of a valid challenge
+    MIN_AGE = -30
+
+    private
+    attr_accessor :version, :time, :client_ip, :random, :digest, :invalid_buffer
+
+    public
+
+    # Parse a challenge.
+    #
+    # The resulting challenge may not be valid! You should call {#valid?} on it before
+    # making assumptions.
+    #
+    # @param [String] string  A return value of {Octokey::Challenge.to_s}
+    # @return [Octokey::Challenge]
+    # @raise [Octokey::InvalidBuffer]
+    #
+    def self.from_string(string)
+      buffer = Octokey::Buffer.new(string)
+      new.instance_eval do
+        begin
+          self.version = buffer.scan_uint8
+          if version == CHALLENGE_VERSION
+            self.time, self.client_ip, self.random, self.digest =
+              buffer.scan_all(:time, :ip, :varbytes, :varbytes)
+          end
+        rescue InvalidBuffer => e
+          self.invalid_buffer = e.message
+        end
+
+        self
+      end
+    end
+
+    # Generate a new challenge.
+    #
+    # @param [Hash] opts
+    # @option opts [IPAddr, String] :client_ip  The IP address of the client
+    # @option opts [Time] :current_time  (Time.now) The current time
+    # @return [Octokey::Challenge]
+    #
+    def self.generate(opts = {})
+      new.instance_eval do
+        expected_ip  = IPAddr(opts[:client_ip])
+        current_time = opts[:current_time] || Time.now
+
+        self.version = CHALLENGE_VERSION
+        self.time = current_time
+        self.client_ip = expected_ip
+        self.random = SecureRandom.random_bytes(RANDOM_SIZE)
+        self.digest = expected_digest
+        self
+      end
+    end
+
+    # Is this challenge valid?
+    #
+    # @param [Hash] opts
+    # @option opts [IPAddr, String] :client_ip  The IP address of the client
+    # @option opts [Time] :current_time  (Time.now) The current time
+    # @return [Boolean]
+    #
+    def valid?(opts)
+      errors(opts) == []
+    end
+
+
+    # What errors were encountered parsing this challenge?
+    #
+    # @param [Hash] opts
+    # @option opts [IPAddr, String] :client_ip  The IP address of the client
+    # @option opts [Time] :current_time  (Time.now) The current time
+    # @return [Array<String>]
+    #
+    def errors(opts)
+      expected_ip  = IPAddr(opts[:client_ip])
+      current_time = opts[:current_time] || Time.now
+
+      return [invalid_buffer] unless invalid_buffer.nil?
+      return ["Challenge version mismatch"] unless version == CHALLENGE_VERSION
+
+      errors = []
+      errors << "Challenge too old"          unless current_time < time + MAX_AGE
+      errors << "Challenge too new"          unless current_time > time + MIN_AGE
+      errors << "Challenge IP mismatch"      unless client_ip == expected_ip
+      errors << "Challenge random mismatch"  unless random.size == RANDOM_SIZE
+      errors << "Challenge HMAC mismatch"    unless digest == expected_digest
+
+      errors
+    end
+
+    # Return a the challenge serialized into a buffer.
+    #
+    # @return [String]
+    def to_buffer
+      unsigned_buffer.
+        add_varbytes(digest)
+    end
+
+    # Return a Base64-encoded copy of this challenge serialized into a buffer.
+    #
+    # @return [String]
+    def to_s
+      to_buffer.to_s
+    end
+
+    # Return a string suitable for identifying this challenge while debugging.
+    #
+    # @return [String]
+    def inspect
+      "#<Octokey::Challenge @version=#{version.inspect} @time=#{time.inspect}" +
+        "@client_ip=#{client_ip.inspect}>"
+    end
+
+    private
+
+    # The digest calculated from the remainder of the challenge
+    #
+    # @return [String]
+    def expected_digest
+      OpenSSL::HMAC.digest(HMAC_ALGORITHM, Octokey::Config.hmac_secret, unsigned_buffer.raw)
+    end
+
+    # A buffer containing everything except the signature
+    #
+    # @return [Octokey::Buffer]
+    def unsigned_buffer
+      Octokey::Buffer.new.
+        add_uint8(version).
+        add_time(time).
+        add_ip(client_ip).
+        add_varbytes(random)
+    end
+
+    # Convert a provided parameter into an IPAddr.
+    #
+    # @param [IPAddr, String] x
+    # @return [IPAddr]
+    # @raise [ArgumentError]
+    def IPAddr(x)
+      x && IPAddr.new(x.to_s) or raise ArgumentError, "no client IP given"
+    end
+  end
+end

data/lib/octokey/config.rb

@@ -0,0 +1,101 @@
+class Octokey
+  # All configuration for Octokey is stored here.
+  class Config
+    # Configure the hmac_secret for Octokey.
+    #
+    # This should be a long random string, such as might be generated with:
+    # $ head -c48 /dev/random | base64
+    #
+    def self.hmac_secret=(secret)
+      @hmac_secret = secret.to_str
+    end
+
+    # Which hostnames does your website use?
+    #
+    # This should be an array, for example ["example.com", "*.example.org"]
+    # *.example.org will match bar.example.org, foo.bar.example.org, etc.
+    # example.com will only match example.com
+    def self.valid_hostnames=(hostnames)
+      @valid_hostnames = hostnames.to_ary
+    end
+
+    # Given a username which public keys should they be allowed to log in with
+    #
+    # Your block should only return strings that you obtained through Octokey#public_key
+    # as part of the sign up flow. They have the same format as ssh keys found in the
+    # ~/.authorized_keys file.
+    #
+    # @example
+    #   Octokey::Config.public_keys do |username, opts|
+    #     User.find_by_username(username).public_keys
+    #   end
+    #
+    def self.public_keys(&block)
+      @public_keys_block = block
+    end
+
+    # Given a string, get an Octokey::Challenge.
+    #
+    # NOTE: this is an advanced feature, you only need to implement this method
+    # if you subclass Octokey::Challenge.
+    def self.challenge(&block)
+      @challenge_block = block
+    end
+
+    # Given a string, get an Octokey::AuthRequest.
+    #
+    # NOTE: this is an advanced feature, you only need to implement this method
+    # if you subclass Octokey::AuthRequest.
+    def self.auth_request(&block)
+      @auth_request_block = block
+    end
+
+    # Get the HMAC secret previously configured
+    # @return [String]
+    def self.hmac_secret
+      @hmac_secret or raise "You must configure Octokey::Config.hmac_secret = FOO"
+    end
+
+    # Get the valid hostnames previously configured
+    # @return [Array<String>]
+    def self.valid_hostnames
+      @valid_hostnames or raise "You must configure Octokey::Config.valid_hostnames = ['example.com']"
+    end
+
+    # Get a new Octokey::Challenge instance
+    # @param [String] string  The Base64-encoded challenge
+    # @param [Hash] opts  Passed to Octokey.new
+    # @return [Octokey::Challenge]
+    def self.get_challenge(string, opts)
+      @challenge_block.call(string, opts)
+    end
+
+    # Get a new Octokey::AuthRequest instance
+    # @param [String] string  The Base64-encoded auth_request
+    # @param [Hash] opts  Passed to Octokey.new
+    # @return [Octokey::AuthRequest]
+    def self.get_auth_request(string, opts)
+      @auth_request_block.call(string, opts)
+    end
+
+    # Get the public keys associated with the given username.
+    # @param [String] username  The claimed username
+    # @param [Hash] opts  Passed to Octokey.new
+    # @return [Array<String>]
+    def self.get_public_keys(username, opts)
+      @public_keys_block.call(username, opts)
+    end
+
+    challenge do |string, opts|
+      Octokey::Challenge.from_string(string)
+    end
+
+    auth_request do |string, opts|
+      Octokey::AuthRequest.from_string(string)
+    end
+
+    public_keys do |username, opts|
+      raise NotImplementedError, "You must configure Octokey::Config.public_keys{ |username, opts| [] }"
+    end
+  end
+end

data/lib/octokey/public_key.rb

@@ -0,0 +1,157 @@
+class Octokey
+  # With Octokey each user has multiple public keys associated with their account.
+  #
+  # This class deals with parsing, formatting, and verifying public keys that are
+  # input.
+  class PublicKey
+
+    # The only type of PublicKey that Octokey supports is RSA.
+    TYPE = "ssh-rsa"
+    # In order to guard against client errors, we disallow short, weak, keys.
+    SSH_RSA_MINIMUM_MODULUS_SIZE = 768
+
+    private
+    attr_accessor :expected_type, :type, :e, :n, :invalid_buffer
+
+    public
+
+    # Wrap an existing public key.
+    #
+    # @param [OpenSSL::PKey::RSA] key
+    # @return [Octokey::PublicKey]
+    # @raise [ArgumentError] if the key was not an rsa key
+    def self.from_key(key)
+      raise ArgumentError, "Invalid key type" unless OpenSSL::PKey::RSA === key
+      new.instance_eval do
+        self.e = key.e
+        self.n = key.n
+        self.type = TYPE
+        self
+      end
+    end
+
+    # Extract a public key from a buffer.
+    #
+    # If parsing fails then the returned Octokey::PublicKey's .valid? method
+    # will return false.
+    #
+    # @param [Octokey::Buffer] buffer
+    # @param [String] expected_type (nil)
+    # @return [Octokey::PublicKey]
+    def self.from_buffer(buffer, expected_type = nil)
+      new.instance_eval do
+        begin 
+          self.expected_type = expected_type
+          self.type = buffer.scan_string
+          if type == TYPE
+            self.e, self.n = buffer.scan_all(:mpint, :mpint)
+          end
+        rescue Octokey::InvalidBuffer => e
+          self.invalid_buffer = e.message
+        end
+
+        self
+      end
+    end
+
+    # Parse the string representation of a public key.
+    #
+    # The string representation used matches exactly the format which ssh uses
+    # to store public keys in the ~/.ssh/authorized_keys file:
+    #  "ssh-rsa <base64-encoded-buffer>"
+    #
+    # If parsing fails then the returned Octokey::PublicKey's .valid? method
+    # will return false.
+    #
+    # @param [String] string  the string to parse
+    # @return [Octokey::PublicKey]
+    def self.from_string(string)
+      if string =~ /\A([^\s]+)\s+([^\s]+)/
+        from_buffer(Octokey::Buffer.new($2), $1)
+      else
+        new.instance_eval do
+          self.invalid_buffer = "Badly formatted public key"
+          self
+        end
+      end
+    end
+
+    # Is this a correct valid public key?
+    #
+    # If this method returns false, the .errors method can be used to get a
+    # more detailed error message.
+    #
+    # @return [Boolean]
+    def valid?
+      errors == []
+    end
+
+    # What was wrong with this public key?
+    #
+    # @return [Array<String>] the problems
+    def errors
+      if invalid_buffer
+        [invalid_buffer]
+      elsif expected_type && type != expected_type
+        ["Public key type mismatch"]
+      elsif type != TYPE
+        ["Public key type unsupported"]
+      elsif n.num_bits < SSH_RSA_MINIMUM_MODULUS_SIZE
+        ["Public key too small"]
+      else
+        []
+      end
+    end
+
+    # The OpenSSL::PKey::RSA version of this public key.
+    #
+    # @return [OpenSSL::PKey::RSA]  the public key
+    # @raise [RuntimeError]  if the Octokey::PublicKey is not valid
+    def public_key
+      raise RuntimeError, "Tried to read invalid public_key" unless valid?
+      key = OpenSSL::PKey::RSA.new
+      key.e = e
+      key.n = n
+      key
+    end
+
+    # Store the public key into a buffer.
+    #
+    # @return [Octokey::Buffer]
+    def to_buffer
+      Octokey::Buffer.new.
+        add_string(type).
+        add_mpint(e).
+        add_mpint(n)
+    end
+
+    # Get the string representation of this key.
+    # 
+    # @return [String]
+    def to_s
+      "#{type.to_s} #{to_buffer.to_s}"
+    end
+
+    # Get a string representation of this key suitable for use while debugging.
+    #
+    # @return [String]
+    def inspect
+      "#<Octokey::PublicKey #{to_s.inspect}>"
+    end
+
+    # Return a hash code suitable for storing public keys in a ruby Hash.
+    #
+    # @return [Fixnum]
+    def hash
+      to_s.hash ^ self.class.hash
+    end
+
+    # Compare this public key to another.
+    #
+    # @return [Boolean]
+    def ==(other)
+      self.hash == other.hash && self.to_s == other.to_s
+    end
+    alias_method :eql?, :==
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification 
+name: octokey
+version: !ruby/object:Gem::Version 
+  prerelease: 4
+  version: 0.1.pre.2
+platform: jruby
+authors: 
+  - Conrad Irwin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-30 00:00:00 Z
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: rspec
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :development
+    version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: active_support
+    prerelease: false
+    requirement: &id002 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :development
+    version_requirements: *id002
+  - !ruby/object:Gem::Dependency 
+    name: i18n
+    prerelease: false
+    requirement: &id003 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :development
+    version_requirements: *id003
+  - !ruby/object:Gem::Dependency 
+    name: simplecov
+    prerelease: false
+    requirement: &id004 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :development
+    version_requirements: *id004
+  - !ruby/object:Gem::Dependency 
+    name: jruby-openssl
+    prerelease: false
+    requirement: &id005 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :runtime
+    version_requirements: *id005
+description: Allows you to use secure authentication mechanisms in place of passwords
+email: conrad.irwin@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+  - lib/octokey.rb
+  - lib/octokey/auth_request.rb
+  - lib/octokey/buffer.rb
+  - lib/octokey/challenge.rb
+  - lib/octokey/config.rb
+  - lib/octokey/public_key.rb
+homepage: https://github.com/octokey/octokey-gem
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 1.3.1
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Public key authentication for the web!
+test_files: []
+