keepassx 0.1.0

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.8.7-p249@keepassx --create

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.1
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+gemspec
+
+gem 'rake', '0.8.7'

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    keepassx (0.1.0)
+      fast-aes (~> 0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    fast-aes (0.1.1)
+    rake (0.8.7)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  keepassx!
+  rake (= 0.8.7)
+  rspec (= 2.11.0)

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+task :default => :spec
+
+RSpec::Core::RakeTask.new(:spec)

data/keepassx.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name = "keepassx"
+  s.summary = "Ruby API access for KeePassX databases"
+  s.description = "See http://github.com/pitluga/keepassx"
+  s.version = "0.1.0"
+  s.authors = ["Tony Pitluga", "Paul Hinze"]
+  s.email = ["tony.pitluga@gmail.com", "paul.t.hinze@gmail.com"]
+  s.homepage = "http://github.com/pitluga/keepassx"
+  s.files = `git ls-files`.split("\n")
+
+  s.add_dependency "fast-aes", "~> 0.1"
+
+  s.add_development_dependency "rspec", "2.11.0"
+end

data/lib/keepassx.rb

@@ -0,0 +1,13 @@
+require 'base64'
+require 'stringio'
+require 'openssl'
+require 'digest/sha2'
+require 'fast-aes'
+
+require 'keepassx/database'
+require 'keepassx/entry'
+require 'keepassx/entry_field'
+require 'keepassx/group'
+require 'keepassx/group_field'
+require 'keepassx/header'
+require 'keepassx/aes_crypt'

data/lib/keepassx/aes_crypt.rb

@@ -0,0 +1,19 @@
+module Keepassx
+  module AESCrypt
+    def self.decrypt(encrypted_data, key, iv, cipher_type)
+      aes = OpenSSL::Cipher::Cipher.new(cipher_type)
+      aes.decrypt
+      aes.key = key
+      aes.iv = iv unless iv.nil?
+      aes.update(encrypted_data) + aes.final
+    end
+
+    def self.encrypt(data, key, iv, cipher_type)
+      aes = OpenSSL::Cipher::Cipher.new(cipher_type)
+      aes.encrypt
+      aes.key = key
+      aes.iv = iv unless iv.nil?
+      aes.update(data) + aes.final
+    end
+  end
+end

data/lib/keepassx/database.rb

@@ -0,0 +1,45 @@
+module Keepassx
+  class Database
+
+    attr_reader :header, :groups, :entries
+
+    def self.open(path)
+      content = File.respond_to?(:binread) ? File.binread(path) : File.read(path)
+      self.new(content)
+    end
+
+    def initialize(raw_db)
+      @header = Header.new(raw_db[0..124])
+      @encrypted_payload = raw_db[124..-1]
+    end
+
+    def entry(title)
+      @entries.detect { |e| e.title == title }
+    end
+
+    def unlock(master_password)
+      @final_key = header.final_key(master_password)
+      decrypt_payload
+      payload_io = StringIO.new(@payload)
+      @groups = Group.extract_from_payload(header, payload_io)
+      @entries = Entry.extract_from_payload(header, payload_io)
+      true
+    rescue OpenSSL::Cipher::CipherError
+      false
+    end
+
+    def search(pattern)
+      backup = groups.detect { |g| g.name == "Backup" }
+      backup_group_id = backup && backup.group_id
+      entries.select { |e| e.group_id != backup_group_id && e.title =~ /#{pattern}/i }
+    end
+
+    def valid?
+      @header.valid?
+    end
+
+    def decrypt_payload
+      @payload = AESCrypt.decrypt(@encrypted_payload, @final_key, header.encryption_iv, 'AES-256-CBC')
+    end
+  end
+end

data/lib/keepassx/entry.rb

@@ -0,0 +1,81 @@
+# One entry: [FIELDTYPE(FT)][FIELDSIZE(FS)][FIELDDATA(FD)]
+#            [FT+FS+(FD)][FT+FS+(FD)][FT+FS+(FD)][FT+FS+(FD)][FT+FS+(FD)]...
+
+# [ 2 bytes] FIELDTYPE
+# [ 4 bytes] FIELDSIZE, size of FIELDDATA in bytes
+# [ n bytes] FIELDDATA, n = FIELDSIZE
+
+# Notes:
+# - Strings are stored in UTF-8 encoded form and are null-terminated.
+# - FIELDTYPE can be one of the following identifiers:
+#   * 0000: Invalid or comment block, block is ignored
+#   * 0001: UUID, uniquely identifying an entry, FIELDSIZE must be 16
+#   * 0002: Group ID, identifying the group of the entry, FIELDSIZE = 4
+#           It can be any 32-bit value except 0 and 0xFFFFFFFF
+#   * 0003: Image ID, identifying the image/icon of the entry, FIELDSIZE = 4
+#   * 0004: Title of the entry, FIELDDATA is an UTF-8 encoded string
+#   * 0005: URL string, FIELDDATA is an UTF-8 encoded string
+#   * 0006: UserName string, FIELDDATA is an UTF-8 encoded string
+#   * 0007: Password string, FIELDDATA is an UTF-8 encoded string
+#   * 0008: Notes string, FIELDDATA is an UTF-8 encoded string
+#   * 0009: Creation time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 000A: Last modification time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 000B: Last access time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 000C: Expiration time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 000D: Binary description UTF-8 encoded string
+#   * 000E: Binary data
+#   * FFFF: Entry terminator, FIELDSIZE must be 0
+#   '''
+
+module Keepassx
+  class Entry
+    def self.extract_from_payload(header, payload_io)
+      groups = []
+      header.nentries.times do
+        group = Entry.new(payload_io)
+        groups << group
+      end
+      groups
+    end
+
+    attr_reader :fields
+
+    def initialize(payload_io)
+      fields = []
+      begin
+        field = EntryField.new(payload_io)
+        fields << field
+      end while not field.terminator?
+
+      @fields = fields
+    end
+
+    def length
+      @fields.map(&:length).reduce(&:+)
+    end
+
+    def notes
+      @fields.detect { |field| field.name == 'notes' }.data.chomp("\000")
+    end
+
+    def password
+      @fields.detect { |field| field.name == 'password' }.data.chomp("\000")
+    end
+
+    def title
+      @fields.detect { |field| field.name == 'title' }.data.chomp("\000")
+    end
+
+    def username
+      @fields.detect { |field| field.name == 'username' }.data.chomp("\000")
+    end
+
+    def group_id
+      @fields.detect { |field| field.name == 'groupid' }.data
+    end
+
+    def inspect
+      "Entry<title=#{title.inspect}, username=[FILTERED], password=[FILTERED], notes=#{notes.inspect}>"
+    end
+  end
+end

data/lib/keepassx/entry_field.rb

@@ -0,0 +1,49 @@
+module Keepassx
+  class EntryField
+     FIELD_TYPES = [
+       [0x0, 'ignored', :null],
+       [0x1, 'uuid', :ascii],
+       [0x2, 'groupid', :int],
+       [0x3, 'imageid', :int],
+       [0x4, 'title', :string],
+       [0x5, 'url', :string],
+       [0x6, 'username', :string],
+       [0x7, 'password', :string],
+       [0x8, 'notes', :string],
+       [0x9, 'creation_time', :date],
+       [0xa, 'last_mod_time', :date],
+       [0xb, 'last_acc_time', :date],
+       [0xc, 'expiration_time', :date],
+       [0xd, 'binary_desc', :string],
+       [0xe, 'binary_data', :shunt],
+       [0xFFFF, 'terminator', :nil]
+    ]
+    FIELD_TERMINATOR = 0xFFFF
+    TYPE_CODE_FIELD_SIZE = 2   # unsigned short integer
+    DATA_LENGTH_FIELD_SIZE = 4 # unsigned integer
+
+
+    attr_reader :name, :data_type, :data
+
+    def initialize(payload)
+      type_code, @data_length = payload.read(TYPE_CODE_FIELD_SIZE + DATA_LENGTH_FIELD_SIZE).unpack('SI')
+      @name, @data_type = _parse_type_code(type_code)
+      @data = payload.read(@data_length)
+    end
+
+    def terminator?
+      name == 'terminator'
+    end
+
+    def length
+      TYPE_CODE_FIELD_SIZE + DATA_LENGTH_FIELD_SIZE + @data_length
+    end
+
+    def _parse_type_code(type_code)
+      (_, name, data_type) = FIELD_TYPES.detect do |(code, *rest)|
+        code == type_code
+      end
+      [name, data_type]
+    end
+  end
+end

data/lib/keepassx/group.rb

@@ -0,0 +1,56 @@
+# One group: [FIELDTYPE(FT)][FIELDSIZE(FS)][FIELDDATA(FD)]
+#            [FT+FS+(FD)][FT+FS+(FD)][FT+FS+(FD)][FT+FS+(FD)][FT+FS+(FD)]...
+#
+# [ 2 bytes] FIELDTYPE
+# [ 4 bytes] FIELDSIZE, size of FIELDDATA in bytes
+# [ n bytes] FIELDDATA, n = FIELDSIZE
+#
+# Notes:
+# - Strings are stored in UTF-8 encoded form and are null-terminated.
+# - FIELDTYPE can be one of the following identifiers:
+#   * 0000: Invalid or comment block, block is ignored
+#   * 0001: Group ID, FIELDSIZE must be 4 bytes
+#           It can be any 32-bit value except 0 and 0xFFFFFFFF
+#   * 0002: Group name, FIELDDATA is an UTF-8 encoded string
+#   * 0003: Creation time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 0004: Last modification time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 0005: Last access time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 0006: Expiration time, FIELDSIZE = 5, FIELDDATA = packed date/time
+#   * 0007: Image ID, FIELDSIZE must be 4 bytes
+#   * 0008: Level, FIELDSIZE = 2
+#   * 0009: Flags, 32-bit value, FIELDSIZE = 4
+#   * FFFF: Group entry terminator, FIELDSIZE must be 0
+module Keepassx
+  class Group
+    def self.extract_from_payload(header, payload_io)
+      groups = []
+      header.ngroups.times do
+        group = Group.new(payload_io)
+        groups << group
+      end
+      groups
+    end
+
+    def initialize(payload_io)
+      fields = []
+      begin
+        field = GroupField.new(payload_io)
+        fields << field
+      end while not field.terminator?
+
+      @fields = fields
+    end
+
+    def length
+      @fields.map(&:length).reduce(&:+)
+    end
+
+    def group_id
+      @fields.detect { |field| field.name == 'groupid' }.data
+    end
+
+    def name
+      @fields.detect { |field| field.name == 'group_name' }.data.chomp("\000")
+    end
+  end
+end

data/lib/keepassx/group_field.rb

@@ -0,0 +1,44 @@
+module Keepassx
+  class GroupField
+    FIELD_TYPES = [
+      [0x0, 'ignored', :null],
+      [0x1, 'groupid', :int],
+      [0x2, 'group_name', :string],
+      [0x3, 'creation_time', :date],
+      [0x4, 'lastmod_time', :date],
+      [0x5, 'lastacc_time', :date],
+      [0x6, 'expire_time', :date],
+      [0x7, 'imageid', :int],
+      [0x8, 'level', :short],
+      [0x9, 'flags', :int],
+      [0xFFFF, 'terminator', :null]
+    ]
+    FIELD_TERMINATOR = 0xFFFF
+    TYPE_CODE_FIELD_SIZE = 2   # unsigned short integer
+    DATA_LENGTH_FIELD_SIZE = 4 # unsigned integer
+
+
+    attr_reader :name, :data_type, :data
+
+    def initialize(payload)
+      type_code, @data_length = payload.read(TYPE_CODE_FIELD_SIZE + DATA_LENGTH_FIELD_SIZE).unpack('SI')
+      @name, @data_type = _parse_type_code(type_code)
+      @data = payload.read(@data_length)
+    end
+
+    def terminator?
+      name == 'terminator'
+    end
+
+    def length
+      TYPE_CODE_FIELD_SIZE + DATA_LENGTH_FIELD_SIZE + @data_length
+    end
+
+    def _parse_type_code(type_code)
+      (_, name, data_type) = FIELD_TYPES.detect do |(code, *rest)|
+        code == type_code
+      end
+      [name, data_type]
+    end
+  end
+end

data/lib/keepassx/header.rb

@@ -0,0 +1,87 @@
+# The keepass file header.
+#
+# From the KeePass doc:
+#
+# Database header: [DBHDR]
+#
+# [ 4 bytes] DWORD    dwSignature1  = 0x9AA2D903
+# [ 4 bytes] DWORD    dwSignature2  = 0xB54BFB65
+# [ 4 bytes] DWORD    dwFlags
+# [ 4 bytes] DWORD    dwVersion       { Ve.Ve.Mj.Mj:Mn.Mn.Bl.Bl }
+# [16 bytes] BYTE{16} aMasterSeed
+# [16 bytes] BYTE{16} aEncryptionIV
+# [ 4 bytes] DWORD    dwGroups        Number of groups in database
+# [ 4 bytes] DWORD    dwEntries       Number of entries in database
+# [32 bytes] BYTE{32} aContentsHash   SHA-256 hash value of the plain contents
+# [32 bytes] BYTE{32} aMasterSeed2    Used for the dwKeyEncRounds AES
+#                                     master key transformations
+# [ 4 bytes] DWORD    dwKeyEncRounds  See above; number of transformations
+#
+# Notes:
+#
+# - dwFlags is a bitmap, which can include:
+#   * PWM_FLAG_SHA2     (1) for SHA-2.
+#   * PWM_FLAG_RIJNDAEL (2) for AES (Rijndael).
+#   * PWM_FLAG_ARCFOUR  (4) for ARC4.
+#   * PWM_FLAG_TWOFISH  (8) for Twofish.
+# - aMasterSeed is a salt that gets hashed with the transformed user master key
+#   to form the final database data encryption/decryption key.
+#   * FinalKey = SHA-256(aMasterSeed, TransformedUserMasterKey)
+# - aEncryptionIV is the initialization vector used by AES/Twofish for
+#   encrypting/decrypting the database data.
+# - aContentsHash: "plain contents" refers to the database file, minus the
+#   database header, decrypted by FinalKey.
+#   * PlainContents = Decrypt_with_FinalKey(DatabaseFile - DatabaseHeader)
+module Keepassx
+  class Header
+
+    ENCRYPTION_FLAGS = [
+       [1 , 'SHA2'    ],
+       [2 , 'Rijndael'],
+       [2 , 'AES'     ],
+       [4 , 'ArcFour' ],
+       [8 , 'TwoFish' ]
+    ]
+
+    attr_reader :encryption_iv
+    attr_reader :ngroups, :nentries
+
+    def initialize(header_bytes)
+      @signature1 = header_bytes[0..4].unpack('L*').first
+      @signature2 = header_bytes[4..8].unpack('L*').first
+      @flags   = header_bytes[8..12].unpack('L*').first
+      @version = header_bytes[12..16].unpack('L*').first
+      @master_seed = header_bytes[16...32]
+      @encryption_iv = header_bytes[32...48]
+      @ngroups = header_bytes[48..52].unpack('L*').first
+      @nentries = header_bytes[52..56].unpack('L*').first
+      @contents_hash = header_bytes[56..88]
+      @master_seed2 = header_bytes[88...120]
+      @rounds = header_bytes[120..-1].unpack('L*').first
+    end
+
+    def valid?
+      @signature1 == 0x9AA2D903 && @signature2 == 0xB54BFB65
+    end
+
+    def encryption_type
+      ENCRYPTION_FLAGS.each do |(flag_mask, encryption_type)|
+        return encryption_type if @flags & flag_mask
+      end
+      'Unknown'
+    end
+
+    def final_key(master_key)
+      key = Digest::SHA2.new.update(master_key).digest
+      aes = FastAES.new(@master_seed2)
+
+      @rounds.times do |i|
+        key = aes.encrypt(key)
+      end
+
+      key = Digest::SHA2.new.update(key).digest
+      key = Digest::SHA2.new.update(@master_seed + key).digest
+      key
+    end
+  end
+end

data/spec/keepassx/database_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe Keepassx::Database do
+  describe 'self.open' do
+    it "creates a new instance of the databse with the file" do
+      db = Keepassx::Database.open(TEST_DATABASE_PATH)
+      db.should_not be_nil
+    end
+  end
+
+  describe "unlock" do
+    before :each do
+      @db = Keepassx::Database.open(TEST_DATABASE_PATH)
+      @db.should be_valid
+    end
+
+    it "returns true when the master password is correct" do
+      @db.unlock('testmasterpassword').should be_true
+    end
+
+    it "returns false when the master password is incorrect" do
+      @db.unlock('bad password').should be_false
+    end
+  end
+
+  describe "an unlocked database" do
+    before :each do
+      @db = Keepassx::Database.open(TEST_DATABASE_PATH)
+      @db.unlock('testmasterpassword')
+    end
+
+    it "can find entries by their title" do
+      @db.entry("test entry").password.should == "testpassword"
+    end
+
+    it "can find groups" do
+      @db.groups.map(&:name).sort.should == ["Backup", "Internet", "eMail"]
+    end
+
+    it "can search for entries" do
+      entries = @db.search "test"
+      entries.first.title.should == "test entry"
+    end
+
+    it "can search for entries case-insensitively" do
+      entries = @db.search "TEST"
+      entries.first.title.should == "test entry"
+    end
+
+    it "will find the current values of entries with history" do
+      entries = @db.search "entry2"
+      entries.size.should == 1
+      entries.first.title.should == "entry2"
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'keepassx'
+require 'rspec'
+
+TEST_DATABASE_PATH = File.expand_path('../test_database.kdb', __FILE__)

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification 
+name: keepassx
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Tony Pitluga
+- Paul Hinze
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-10-14 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: fast-aes
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 1
+        version: "0.1"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 11
+        - 0
+        version: 2.11.0
+  type: :development
+  version_requirements: *id002
+description: See http://github.com/pitluga/keepassx
+email: 
+- tony.pitluga@gmail.com
+- paul.t.hinze@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .rvmrc
+- .travis.yml
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- keepassx.gemspec
+- lib/keepassx.rb
+- lib/keepassx/aes_crypt.rb
+- lib/keepassx/database.rb
+- lib/keepassx/entry.rb
+- lib/keepassx/entry_field.rb
+- lib/keepassx/group.rb
+- lib/keepassx/group_field.rb
+- lib/keepassx/header.rb
+- spec/keepassx/database_spec.rb
+- spec/spec_helper.rb
+- spec/test_database.kdb
+has_rdoc: true
+homepage: http://github.com/pitluga/keepassx
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Ruby API access for KeePassX databases
+test_files: []
+