keybox 1.0.0

data/lib/keybox/cipher.rb

@@ -0,0 +1,6 @@
+module Keybox
+    module Cipher
+        AES_256             = "aes-256-cbc"
+        DEFAULT_ALGORITHM   = AES_256
+    end
+end

data/lib/keybox/convert.rb

@@ -0,0 +1 @@
+require 'keybox/convert/csv'

data/lib/keybox/convert/csv.rb

@@ -0,0 +1,96 @@
+
+require 'csv'
+require 'keybox/entry'
+module Keybox
+    module Convert
+        #
+        # Convert to/from a CSV file.  When loading a CSV file, it is assumed
+        # that there is a header on the csv file that shows which of the fields
+        # belongs to the various fields of the entry.  At a minimum the header
+        # line should have the default fields from an HostAccountEntry which are:
+        #
+        #   - title
+        #   - username
+        #   - hostname
+        #   - password
+        #   - additional_info
+        # 
+        # These headers can be in any order and CSV will do the right
+        # thing.  But these headers must exist.  A
+        # Keybox::ValidationError is thrown if they do not.
+        #       
+        class CSV
+            class << self 
+
+                # parse the header line from the CSV file and make sure
+                # that all the required columns are listed.
+                #
+                def parse_header(header) 
+                    field_indexes = {}
+                    Keybox::HostAccountEntry.default_fields.each do |field|
+                        field_indexes[field] = header.index(field)
+                        if field_indexes[field].nil? then
+                            raise Keybox::ValidationError, "There must be a header on the CSV to import and it must contain the '#{field}' field."
+                        end
+                    end
+                    field_indexes
+                end
+
+                # returns an Array of AccountEntry classes or its
+                # descendants
+                #
+                def from_file(csv_filename)
+                    reader = ::CSV.open(csv_filename,"r")
+                    entries = Keybox::Convert::CSV.from_reader(reader)
+                    reader.close
+                    return entries
+                end
+
+                # pull all the items from the CSV file.  There MUST be a
+                # header line that says what the different fields are.
+                # A HostAccountEntry object is created for each line and
+                # the array of those objects is returned
+                #
+                def from_reader(csv_reader)
+                    field_indexes = parse_header(csv_reader.shift)
+                    entries = []
+                    csv_reader.each do |row|
+                        entry = Keybox::HostAccountEntry.new
+                        field_indexes.each_pair do |field,index|
+                            value = row[index] || ""
+                            entry.send("#{field}=",value.strip)
+                        end
+                        entries << entry
+                    end
+                    return entries
+                end
+
+                #
+                # records should be an array of AccountEntry objects
+                #
+                def to_file(records,csv_filename)
+                    writer = ::CSV.open(csv_filename,"w")
+                    Keybox::Convert::CSV.to_writer(records,writer)
+                    writer.close
+                end
+
+                #
+                # write all the fields for each record.  We go through
+                # all the records (an array of AccountEntry objects), 
+                # recording all the fields, then using that as the header.  
+                #
+                def to_writer(records,csv_writer)
+                    field_names = records.collect { |r| r.fields }.flatten.uniq
+                    csv_writer << field_names
+                    records.each do |record|
+                        values = []
+                        field_names.each do |field|
+                            values << record.send(field) || ""
+                        end
+                        csv_writer << values
+                    end
+                end
+            end 
+        end
+    end
+end

data/lib/keybox/digest.rb

@@ -0,0 +1,13 @@
+require 'openssl'
+module Keybox
+    #
+    # By default Keybox wants to use sha-256 as the hashing function.
+    # This is available in OpenSSL 0.9.8 or greater.
+    #
+    module Digest
+        SHA_256             = "sha256"
+        CLASSES             = { SHA_256 => ::OpenSSL::Digest::SHA256 } 
+        DEFAULT_ALGORITHM   = SHA_256
+        ALGORITHMS = CLASSES.keys
+    end
+end

data/lib/keybox/entry.rb

@@ -0,0 +1,200 @@
+require 'keybox/storage/record'
+
+module Keybox
+
+    # Entries in the Keybox storage container.  The base class is
+    # AccountEntry with current child classes HostAccountEntry and
+    # URLAccountEntry.
+    #
+    # In most cases HostAccountEntry will suffice.  Use URLAccountEntry 
+    # when you would like to link an entry's +password+ field to be
+    # generated based upon the master password of the container.
+    class AccountEntry < Keybox::Storage::Record
+        class << self
+            def default_fields
+                %w(title username additional_info)
+            end
+
+            # fields that can be displayed, some could be calculated
+            def display_fields
+                (visible_fields + private_fields).uniq
+            end
+            
+            def private_fields
+                []
+            end
+
+            def visible_fields
+                default_fields - private_fields
+            end
+
+            def visible_field?(field_name)
+                visible_fields.include?(field_name)
+            end
+
+            def private_field?(field_name)
+                private_fields.include?(field_name)
+            end
+        end
+
+        def each
+            fields.each do |f|
+                yield [f,self.send(f)]
+            end
+        end
+
+        # fields that are actually stored in the entry
+        def fields
+            (default_fields + @data_members.keys ).collect { |k| k.to_s }.uniq
+        end
+
+        def default_fields
+            self.class.default_fields
+        end
+
+        def display_fields
+            self.class.display_fields
+        end
+        
+        def private_fields
+            self.class.private_fields
+        end
+
+        def private_field?(field_name)
+            self.class.private_field?(field_name)
+        end
+
+        def visible_fields
+            self.class.visible_fields
+        end
+
+        def visible_field?(field_name)
+            self.class.visible_field?(field_name)
+        end
+
+
+        def values
+            fields.collect { |f| self.send(f) }
+        end
+
+        def initialize(title = "",username = "")
+            super()
+            self.title              = title
+            self.username           = username
+            self.additional_info    = ""
+        end
+
+        def needs_container_passphrase?
+            false
+        end
+
+        def to_s
+            s = StringIO.new
+            max_length = self.max_field_length
+            fields.each do |f|
+                line = "#{f.rjust(max_length + 1)} :"
+                value = self.send(f)
+                if private_field?(f) then
+                    # if its private field, then blank out value just to
+                    value = " ***** private ***** "
+                end
+                s.puts "#{f.rjust(max_length + 1)} : #{value}"
+            end
+            return s.string
+        end
+
+        def max_field_length
+            fields.collect { |f| f.length }.max
+        end
+
+    end
+
+    #
+    # Host Accounts are those typical login accounts on machines.  These
+    # contain at a minimum the fields:
+    #
+    #   - title
+    #   - hostname
+    #   - username
+    #   - pasword
+    #   - additional_info
+    #
+    # Since HostAccountEntry is a descendant of Keybox::Storage::Record
+    # other fields may be added dynamically.
+    #
+    class HostAccountEntry < Keybox::AccountEntry
+        
+        class << self
+            def default_fields
+                %w(title hostname username password additional_info)
+            end
+
+            def private_fields
+                %w(password)
+            end
+        end
+
+        def initialize(title = "",hostname = "",username = "",password = "")
+            super(title,username)
+            self.hostname = hostname
+            self.password = password
+        end
+
+    end
+
+    #
+    # URLAccounts do not have a +password+ field, although it appears
+    # to. It is calculated based upon the URL and the master password
+    # for the Container.  The minimum fields for URLAccountEntry are:
+    #
+    #   - title
+    #   - url
+    #   - username
+    #   - additional_info
+    #
+    # This is inspired by http://crypto.stanford.edu/PwdHash/ and
+    # http://www.xs4all.nl/~jlpoutre/BoT/Javascript/PasswordComposer/
+    #
+    # This class also needs to be told the container's passphrase to
+    # calculate its own password.
+    #
+    # TODO: Have this class use any other Keybox::Storage::Record
+    # for the master password instead of the container.
+    #
+    class URLAccountEntry < Keybox::AccountEntry
+        class << self
+            def initial_fields
+                %w(title url username additional_info)
+            end
+            
+            def private_fields
+                %w(password)
+            end
+        end
+
+        def initialize(title = "",url = "",username = "")
+            super(title,username)
+            self.url = url
+        end
+
+        def password_hash_alg
+            if not instance_variables.include?("@password_hash_alg") then
+                @password_hash_alg = Keybox::PasswordHash.new
+            end
+            @password_hash_alg
+        end
+
+        def needs_container_passphrase?
+            true
+        end
+
+        def container_passphrase=(p)
+            password_hash_alg.master_password = p.dup
+        end
+
+        def password
+            password_hash_alg.password_for_url(self.url)
+        end
+
+    end
+end

data/lib/keybox/error.rb

@@ -0,0 +1,5 @@
+module Keybox
+    class KeyboxError      < ::StandardError ; end
+    class ValidationError  < KeyboxError; end
+    class ApplicationError < KeyboxError; end
+end

data/lib/keybox/password_hash.rb

@@ -0,0 +1,33 @@
+require 'uri'
+require 'digest/sha1'
+module Keybox
+
+    # this is an implementation of the password hash algorithm used at 
+    # http://www.xs4all.nl/~jlpoutre/BoT/Javascript/PasswordComposer/
+    #
+    # This implementation uses the SHA1 hash instead of the MD5
+    #
+    # This class uses a master password and with that information
+    # generates a unique password for all subsequent strings passed to
+    # it.  
+    #
+    class PasswordHash
+
+        attr_writer :master_password
+
+        def initialize(master_password = "")
+            @master_password = master_password
+            @digest_class    = ::Digest::SHA1
+        end
+
+        def password_for_url(url)
+            uri = URI.parse(url)
+            password_for(uri.host)
+        end
+
+        def password_for(str)
+            @digest_class.hexdigest("#{@master_password}:#{str}")[0..8]
+        end
+    end
+
+end

data/lib/keybox/randomizer.rb

@@ -0,0 +1,193 @@
+require 'openssl'
+module Keybox
+
+    ##
+    # Use an IO device to retrieve random data.  Usually this is
+    # somethine like '/dev/random' but may be anything that can read
+    # from by IO.read.
+    #
+    #   bytes = RandomDevice.random_bytes(42)
+    #
+    # or 
+    #
+    #   rd = RandomDevice.new
+    #   bytes = rd.random_bytes(42)
+    #
+    # If there is a some other hardware device or some service that
+    # provides random byte stream, set it as the default device in this
+    # class and it will use it instead of the default.
+    #
+    #   my_random_device = RandomDevice("/dev/super-random-device")
+    #
+    # or 
+    #
+    #   RandomDevice.default = "/dev/super-random-device"
+    #   my_random_device     = RandomDevice.new
+    #   my_random_device.source                        # =>  "/dev/super-random-device"
+    #
+    # All further instances of RandomDevice will use it as the default.
+    #
+    # RandomDevice can either produce random bytes as a class or as an
+    # instance.
+    #
+    #   random_bytes = RandomDevice.random_bytes(42)  
+    #   random_bytes.size                              # => 42
+    #
+    class RandomDevice
+        @@DEVICES = [ "/dev/urandom", "/dev/random" ]
+        @@DEFAULT = nil
+
+        attr_accessor :source
+
+        def initialize(device = nil)
+            if not device.nil? and File.readable?(device) then
+                @source = device
+            else
+                @source = RandomDevice.default
+            end
+        end
+
+        def random_bytes(count = 1)
+            File.read(source,count)
+        end
+        
+        class << self
+            def default
+                return @@DEFAULT unless @@DEFAULT.nil?
+
+                @@DEVICES.each do |device|
+                    if File.readable?(device) then
+                        @@DEFAULT = device 
+                        break
+                    end
+                end
+                return @@DEFAULT
+            end
+
+            def default=(device)
+                if File.readable?(device) then
+                    @@DEVICES << device
+                    @@DEFAULT = device
+                else
+                    raise ArgumentError, "device #{device} is not readable and therefore makes a bad random device"
+                end
+            end
+
+            def random_bytes(count = 1)
+                File.read(RandomDevice.default,count)
+            end
+        end
+    end
+
+
+    #
+    # A RandomSource uses one from a set of possible source
+    # class/modules.  So long as the @@DEFAULT item responds to
+    # +random_bytes+ it is fine.  
+    #
+    # RandomSource supplies a +rand+ method in the same vein as
+    # Kernel#rand.
+    #
+    class RandomSource
+        @@SOURCE_CLASSES = [ ::Keybox::RandomDevice, ::OpenSSL::Random ]
+        @@SOURCE = nil
+
+        class << self
+            def register(klass)
+                if klass.respond_to?("random_bytes") then 
+                    @@SOURCE_CLASSES << klass unless @@SOURCE_CLASSES.include?(klass)
+                else
+                    raise ArgumentError, "class #{klass.name} does not have a 'random_bytes' method"
+                end
+            end
+
+            def source_classes
+                @@SOURCE_CLASSES
+            end
+
+            def source=(klass)
+                register(klass)
+                @@SOURCE = klass
+            end
+
+            def source
+                return @@SOURCE unless @@SOURCE.nil? or not @@SOURCE_CLASSES.include?(@@SOURCE)
+                @@SOURCE_CLASSES.each do |klass|
+                    if klass.random_bytes(2).length == 2 then
+                        RandomSource.source = klass
+                        break
+                    end
+                end
+                @@SOURCE
+            end
+
+            #
+            # Behave like Kernel#rand where if no max is specified return
+            # a value >= 0.0 but < 1.0.
+            #
+            # If a max is specified, return an Integer between 0 and
+            # upto but not including max.
+            #
+            def rand(max = nil)
+                bytes = source.random_bytes(8)
+                num = bytes.unpack("F").first.abs / Float::MAX
+                if max then
+                    num = bytes.unpack("Q").first % max.floor
+                end
+                return num
+            end
+        end
+    end
+
+    #
+    # Randomizer will randomly pick a value from anything that
+    # behaves like an array or has a +to_a+ method.  Behaving like an
+    # array means having a +size+ or +length+ method along with an +at+
+    # method.
+    # 
+    # The source of randomness is determined at runtime.  Any class that
+    # can provide a +rand+ method and operates in the same manner
+    # as Kernel#rand can be a used as the random source.
+    #
+    # The item that is being 'picked' from can be any class that has a
+    # +size+ method along with an +at+ method.
+    #
+    #   array = ("aaa"..."zzz").to_a
+    #   r = Randomizer.new
+    #   r.pick_one_from(array)          # => "lho"
+    #   r.pick_count_from(array,5)      # => ["mvt", "tde", "wdu", "ker", "bgc"]
+    #
+    #
+    class Randomizer 
+
+        REQUIRED_METHODS = %w( at size )
+
+        attr_reader :random_source
+
+        def initialize(random_source_klass = ::Keybox::RandomSource)
+            raise ArgumentError, "Invalid random source class" unless random_source_klass.respond_to?("rand")
+            @random_source = random_source_klass
+        end
+
+        def pick_one_from(array)
+            pick_count_from(array).first
+        end
+
+        def pick_count_from(array, count = 1)
+            raise ArgumentError, "Unable to pick from object of class #{array.class.name}" unless has_correct_duck_type?(array)
+            results = []
+            range = array.size
+            count.times do
+                rand_index = random_source.rand(range)
+                results << array.at(rand_index)
+            end
+            results
+        end
+
+        private
+
+        def has_correct_duck_type?(obj)
+            (REQUIRED_METHODS & obj.public_methods).size == REQUIRED_METHODS.size
+        end
+    end
+end