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

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