filesafe 1.0.0 → 1.1.0

data/README.txt

@@ -18,10 +18,62 @@ environments (Windows) however.
 This script was written and tested using Ruby 1.9.x.  No attempts to
 adapt or test it under earlier Ruby versions have been made.
 
+ENCRYPTED FILE FORMAT
+
+Before a file is encrypted, some cryptographically secure random data
+is obtained:
+
+  SALT  = securely generated random salt data
+  F_KEY = securely generated random key data
+  F_IV  = securely generated random initialization vector data
+
+The F_KEY and F_IV will be used to encrypt the plaintext file.  In
+order to keep them secure, they will be encrypted using a master key
+and initialization vector derived from the passphrase supplied by
+the user and the SALT.
+
+  PASS  = passphrase supplied by the user of the utility
+  M_KEY = master key derived as described below
+  M_IV  = master initilization vector derived as described below
+
+In order to derive M_KEY and M_IV, the PBKDF2 algorithm as described
+in RFC2898 is used, passing PASS and SALT to it, using the configured
+hash (SHA-512 by default) and number of iterations (4096 by default).
+
+Once M_KEY and M_IV are obtained, 256-bit AES in CBC mode is used to
+encrypt F_KEY + F_IV to obtain:
+
+  C_F_KEY = ciphertext encrypted version of F_KEY, encrypted using M_KEY and  M_IV
+  C_F_IV  = ciphertext encrypted version of F_IV, encrypted using M_KEY and M_IV
+
+A new file is opened, and SALT + C_F_KEY + C_F_IV are written.  The
+contents of the plaintext file are then encrypted using F_KEY and F_IV
+and written to the new file following the salt and encrypted key and vector.
+
+Finally, a HMAC of SALT + C_F_KEY + C_F_IV + encrypted file text is written
+to the end of the new file and it is closed.
+
+This new file is the encrypted file.  The old plaintext file is overwritten and
+removed.
+
+The HMAC uses the same PASS passphrase and the same hash algorithm that
+PBKDF2 uses (SHA-512 by default).
+
+To recover the file, an HMAC is calculated on the encrypted file contents
+excluding the trailing saved HMAC data appended to the end.  This calculated
+HMAC is compared to the saved HMAC.  If they don't match, then either the
+file has been corrupted, or the passphrase is incorrect or different.
+
+If the HMACs match, the SALT is read from the start of the file as well
+as the encrypted master key material C_F_KEY and C_F_IV.  Using PBKDF2
+and the SALT and PASS, the master key material is recovered, M_KEY and M_IV,
+which then are used to decrypt the file keys F_KEY and F_IV.  These file
+keys are used to decrypt and recover the plaintext.
+
 
 LICENSE
 
-This script is licensed under an MIT-style license.  See the license header at the top of the script source code.
+This script is licensed under an MIT-style license.  See the LICENSE.txt file.
 
 
 REQUIREMENTS

data/Rakefile

@@ -1,5 +1,6 @@
 require 'rake/gempackagetask'
 require 'rake/rdoctask'
+require 'rake/testtask'
 
 gemspec = Gem::Specification.new do |spec|
   spec.name         = 'filesafe'
@@ -11,11 +12,13 @@ gemspec = Gem::Specification.new do |spec|
   spec.description  = 'A utility script for encrypting and decrypting files using a randomly generated 256-bit AES key and initialization vector secured using the PBKDF2 password/passphrase key derivation algorithm to secure the file key and IV.'
   spec.has_rdoc     = false ## No documentation yet
   spec.extra_rdoc_files = [ 'README.txt' ]
-  spec.files = [
+  spec.files = FileList[
     'README.txt',
     'VERSION.txt',
     'Rakefile',
-    'bin/filesafe'
+    'bin/*',
+    'lib/*',
+    'test/*'
   ]
   spec.executables = [ 'filesafe' ]
   spec.add_dependency('pbkdf2', '>= 0.1.0')
@@ -34,6 +37,11 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README.txt')
 end
 
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
 task :default => [
   'pkg/filesafe-' + File.open('VERSION.txt','r').to_a.join.strip + '.gem',
   :rdoc

data/VERSION.txt

@@ -1 +1 @@
-1.0.0
+1.1.0

data/bin/filesafe

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 #
 # FileSafe
-# Version: 1.0.0
+# Version: 1.1.0
 # From:    http://www.aarongifford.com/computers/filesafe/index.html
 #
 # A simple file encryption/decryption script that uses 256-bit AES encryption,
@@ -29,11 +29,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require 'openssl'       ## Encryption/HMAC/Hash algorithms
-require 'securerandom'  ## Cryptographically secure source of random data
-require 'pbkdf2'        ## PBKDF2 algorithm for key material generation
-require 'highline'      ## For reading a passphrase from a terminal
-require 'tempfile'      ## Temporary file creation
+require 'filesafe' 
 
 def usage(msg)
   STDERR.puts <<-EOM
@@ -66,8 +62,8 @@ while ARGV.size > 0 && ARGV[0][0,1] == '-'
     usage "Please specify a passphrase and one or more files." if ARGV.size < 2
     opt[:phrase] = ARGV.shift
   when '-n'
-    ARV.shift
-    usage "This option only applies to decryption operations." unless opt.key?(:decrypt)
+    ARGV.shift
+    usage "This option only applies to decryption operations." unless opt[:op] == :decrypt
     opt[:notemp] = true
   when '--'
     break
@@ -78,270 +74,14 @@ end
 usage "You did not specify a -e encrypt or -d decrypt operation." unless opt.key?(:op)
 usage "You must specify one or more files to operate on." if ARGV.size == 0
 
-
-## CONFIGURATION ITEMS:
-PASSHASH_SUFFIX  = '.pass'
-CIPHER           = 'aes-256-cbc'
-cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
-BLOCK_LEN        = cipher.block_size
-KEY_LEN          = cipher.key_len
-IV_LEN           = cipher.iv_len
-SALT_LEN         = KEY_LEN + IV_LEN
-HMAC_FUNC        = 'sha512'
-HMAC_LEN         = OpenSSL::HMAC.new('', HMAC_FUNC).digest.bytesize
-HEADER_LEN       = KEY_LEN + IV_LEN + SALT_LEN + HMAC_LEN
-ITERATIONS       = 4096
-FILE_CHUNK_LEN   = 65536
-
-def getphrase(check=false)
-  begin
-    phrase = HighLine.new.ask('Passphrase: '){|q| q.echo = '*' ; q.overwrite = true }
-    return phrase unless check
-    tmp = HighLine.new.ask('Retype passphrase: '){|q| q.echo = '*' ; q.overwrite = true }
-    return phrase if tmp == phrase
-  rescue Interrupt
-    exit -1
-  end while true
-end
-
-def encrypt_file(file, passphrase=nil)
-  raise "Cannot encrypt non-existent file: #{file.inspect}" unless File.exist?(file)
-  raise "Cannot encrypt unreadable file: #{file.inspect}" unless File.readable?(file)
-  raise "Cannot encrypt unwritable file: #{file.inspect}" unless File.writable?(file)
-  passhash   = false
-  if File.exist?(file + PASSHASH_SUFFIX)
-    raise "Cannot read password hash temporary file: #{(file + PASSHASH_SUFFIX).inspect}" unless File.readable?(file + PASSHASH_SUFFIX)
-    raise "Password hash temporary file length is invalid: #{(file + PASSHASH_SUFFIX).inspect}" unless File.size(file + PASSHASH_SUFFIX) == SALT_LEN + HMAC_LEN
-    fp = File.open(file + PASSHASH_SUFFIX, File::RDONLY)
-    salt = fp.read(SALT_LEN)
-    passcheck = fp.read(HMAC_LEN)
-    loop do
-      passphrase = getphrase if passphrase.nil?
-      pbkdf2data = PBKDF2.new do |p|
-        p.hash_function = HMAC_FUNC
-        p.password      = passphrase
-        p.salt          = salt
-        p.iterations    = ITERATIONS
-        p.key_length    = HMAC_LEN
-      end.bin_string
-      break if passcheck == pbkdf2data
-      puts "*** ERROR: Passphrase mismatch. Try again, abort, or delete temporary file: #{file + PASSHASH_SUFFIX}"
-      passphrase = nil
-    end 
-    passhash = true
-  elsif passphrase.nil?
-    puts "*** ALERT: Enter your NEW passphrase twice. DO NOT FORGET IT, or you may lose your data!"
-    passphrase = getphrase(true)
-  end
-
-  ## Use secure random data to populate salt, key, and IV:
-  salt         = SecureRandom.random_bytes(SALT_LEN)  ## Acquire some fresh salt
-  file_key  = SecureRandom.random_bytes(KEY_LEN)   ## Get some random key material
-  file_iv   = SecureRandom.random_bytes(IV_LEN)    ## And a random initialization vector
-
-  ## Encrypt the file key and IV using password-derived keying material:
-  keymaterial = PBKDF2.new do |p|
-    p.hash_function = HMAC_FUNC
-    p.password      = passphrase
-    p.salt          = salt
-    p.iterations    = ITERATIONS
-    p.key_length    = KEY_LEN + IV_LEN
-  end.bin_string
-  cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
-  cipher.encrypt
-  ## No padding required for this operation since the file key + IV is
-  ## an exact multiple of the cipher block length:
-  cipher.padding = 0
-  cipher.key     = keymaterial[0,KEY_LEN]
-  cipher.iv      = keymaterial[KEY_LEN,IV_LEN]
-  encrypted_keymaterial = cipher.update(file_key + file_iv) + cipher.final
-  encrypted_file_key = encrypted_keymaterial[0,KEY_LEN]
-  encrypted_file_iv  = encrypted_keymaterial[KEY_LEN,IV_LEN]
-
-  ## Open the plaintext file for reading (and later overwriting):
-  rfp = File.open(file, File::RDWR|File::EXCL)
-
-  ## Open a temporary ciphertext file for writing:
-  wfp = Tempfile.new(File.basename(rfp.path), File.dirname(rfp.path))
-
-  ## Write the salt and encrypted file key + IV and
-  ## temporarily fill the HMAC slot with zero-bytes:
-  wfp.write(salt + encrypted_file_key + encrypted_file_iv + (0.chr * HMAC_LEN))
-
-  ## Start the HMAC:
-  hmac = OpenSSL::HMAC.new(passphrase, HMAC_FUNC)
-  hmac << salt
-  hmac << encrypted_file_key
-  hmac << encrypted_file_iv
-
-  ## Encrypt file with file key + IV:
-  cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
-  cipher.encrypt
-  ## Encryption of file contents uses PCKS#5 padding which OpenSSL should
-  ## have enabled by default.  Nevertheless, we explicitly enable it here:
-  cipher.padding = 1
-  cipher.key     = file_key
-  cipher.iv      = file_iv
-  until rfp.eof?
-    data = rfp.read(FILE_CHUNK_LEN)
-    if data.bytesize > 0
-      data = cipher.update(data)
-      hmac << data
-      wfp.write(data)
-    end
-  end
-  data = cipher.final
-  if data.bytesize > 0
-    ## Save the last bit-o-data and update the HMAC:
-    wfp.write(data) 
-    hmac << data
-  end
-
-  ## Write HMAC digest to file:
-  wfp.pos = SALT_LEN + KEY_LEN + IV_LEN
-  wfp.write(hmac.digest)
-
-  ## Overwrite the original plaintext file with zero bytes.
-  ## This adds a small measure of security against recovering
-  ## the original unencrypted contents.  It would likely be
-  ## better to overwrite the file multiple times with different
-  ## bit patterns, including one or more iterations using
-  ## high-quality random data.
-  rfp.seek(0,File::SEEK_END)
-  fsize = rfp.pos
-  rfp.pos = 0
-  while rfp.pos + FILE_CHUNK_LEN < fsize
-    rfp.write(0.chr * FILE_CHUNK_LEN)
-  end
-  rfp.write(0.chr * (fsize - rfp.pos)) if rfp.pos < fsize
-  rfp.close
-
-  ## Copy file ownership/permissions:
-  stat = File.stat(rfp.path)
-  wfp.chown(stat.uid, stat.gid)
-  wfp.chmod(stat.mode)
-
-  ## Close the ciphertext temporary file without deleting:
-  wfp.close(false)
-
-  ## Rename temporary file to permanent name:
-  File.rename(wfp.path, rfp.path)
-
-  ## Remove password hash temp. file:
-  File.delete(file + PASSHASH_SUFFIX) if passhash
-
-  puts "ENCRYPTED: #{file}"
-end
-
-def decrypt_file(file, passphrase=nil, notemp=nil)
-  raise "Cannot decrypt non-existent file: #{file.inspect}" unless File.exist?(file)
-  raise "Cannot decrypt unreadable file: #{file.inspect}" unless File.readable?(file)
-  raise "Cannot decrypt unwritable file: #{file.inspect}" unless File.writable?(file)
-  fsize = File.size(file)
-  raise "File is not in valid encrypted format: #{file.inspect}" unless fsize > HEADER_LEN && (fsize - HEADER_LEN) % BLOCK_LEN == 0
-  salt = encrypted_file_key = encrypted_file_iv = nil
-  loop do
-    passphrase = getphrase if passphrase.nil?
-    fp = File.open(file, File::RDONLY)
-    salt                  = fp.read(SALT_LEN)
-    encrypted_file_key = fp.read(KEY_LEN)
-    encrypted_file_iv  = fp.read(IV_LEN)
-    file_hmac             = fp.read(HMAC_LEN)
-    test_hmac = OpenSSL::HMAC.new(passphrase, HMAC_FUNC)
-    test_hmac << salt
-    test_hmac << encrypted_file_key
-    test_hmac << encrypted_file_iv
-    until fp.eof?
-      data = fp.read(FILE_CHUNK_LEN)
-      test_hmac << data unless data.bytesize == 0
-    end
-    fp.close
-    break if test_hmac.digest == file_hmac
-    puts "*** ERROR: Incorrect passphrase, or file is not encrypted. Try again or abort."
-    passphrase = nil
-  end
-
-  ## Extract and decrypt the encrypted file key + IV.
-  ## First, regenerate the password-based key material that encrypts the
-  ## file key + IV:
-  keymaterial = PBKDF2.new do |p|
-    p.hash_function = HMAC_FUNC
-    p.password      = passphrase
-    p.salt          = salt
-    p.iterations    = ITERATIONS
-    p.key_length    = KEY_LEN + IV_LEN
-  end.bin_string
-  cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
-  cipher.decrypt
-  cipher.padding = 0 ## No padding is required for this operation
-  cipher.key     = keymaterial[0,KEY_LEN]
-  cipher.iv      = keymaterial[KEY_LEN,IV_LEN]
-  ## Decrypt file key + IV:
-  keymaterial = cipher.update(encrypted_file_key + encrypted_file_iv) + cipher.final
-  file_key = keymaterial[0,KEY_LEN]
-  file_iv  = keymaterial[KEY_LEN,IV_LEN]
-
-  ## Decrypt file:
-  cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
-  cipher.decrypt
-  cipher.padding = 1 ## File contents use PCKS#5 padding,OpenSSL's default method
-  cipher.key     = file_key
-  cipher.iv      = file_iv
-
-  ## Open ciphertext file for reading:
-  rfp = File.open(file, File::RDONLY|File::EXCL)
-
-  ## Open a temporary plaintext file for writing:
-  wfp = Tempfile.new(File.basename(rfp.path), File.dirname(rfp.path))
-
-  ## Begin reading the ciphertext beyond the headers:
-  rfp.pos = HEADER_LEN  ## Skip headers
-  until rfp.eof?
-    data = rfp.read(FILE_CHUNK_LEN)
-    if data.bytesize > 0
-      data = cipher.update(data)
-      wfp.write(data)
-    end
-  end
-  data = cipher.final
-  wfp.write(data) if data.bytesize > 0
-
-  ## Close the ciphertext source file:
-  rfp.close
-
-  ## Copy file ownership/permissions:
-  stat = File.stat(rfp.path)
-  wfp.chown(stat.uid, stat.gid)
-  wfp.chmod(stat.mode)
-
-  ## Close the plaintext temporary file without deleting:
-  wfp.close(false)
-
-  ## Rename temporary file to permanent name:
-  File.rename(wfp.path, rfp.path)
-
-  if notemp.nil?
-    ## Write password hash temp. file using PBKDF2 as an iterated hash of sorts of HMAC_LEN bytes:
-    salt = SecureRandom.random_bytes(SALT_LEN)  ## Grab a new chunk of random data
-    pbkdf2data = PBKDF2.new do |p|
-      p.hash_function = HMAC_FUNC
-      p.password      = passphrase
-      p.salt          = salt
-      p.iterations    = ITERATIONS
-      p.key_length    = HMAC_LEN
-    end.bin_string
-    File.open(file + PASSHASH_SUFFIX, File::WRONLY|File::EXCL|File::CREAT) {|f| f.write(salt + pbkdf2data)}
-  end
-
-  puts "FILE DECRYPTED: #{file}"
-end
-
 ARGV.each do |file|
   begin
     if opt[:op] == :decrypt
-      decrypt_file(file, opt[:phrase], opt[:notemp])
+      FileSafe.decrypt(file, opt[:phrase], opt[:notemp])
+      puts "FILE DECRYPTED: #{file}"
     else
-      encrypt_file(file, opt[:phrase])
+      FileSafe.encrypt(file, opt[:phrase])
+      puts "ENCRYPTED: #{file}"
     end
   rescue StandardError => e
     STDERR.puts "*** Error while working on file #{file.inspect}: #{e}"

data/lib/filesafe.rb

@@ -0,0 +1,265 @@
+#!/usr/bin/env ruby
+
+module FileSafe
+  require 'openssl'       ## Encryption/HMAC/Hash algorithms
+  require 'securerandom'  ## Cryptographically secure source of random data
+  require 'pbkdf2'        ## PBKDF2 algorithm for key material generation
+  require 'highline'      ## For reading a passphrase from a terminal
+  require 'tempfile'      ## Temporary file creation
+
+  ## CONFIGURATION ITEMS:
+  PASSHASH_SUFFIX  = '.pass'
+  CIPHER           = 'aes-256-cbc'
+  cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
+  BLOCK_LEN        = cipher.block_size
+  KEY_LEN          = cipher.key_len
+  IV_LEN           = cipher.iv_len
+  SALT_LEN         = KEY_LEN + IV_LEN
+  HMAC_FUNC        = 'sha512'
+  HMAC_LEN         = OpenSSL::HMAC.new('', HMAC_FUNC).digest.bytesize
+  HEADER_LEN       = KEY_LEN + IV_LEN + SALT_LEN + HMAC_LEN
+  ITERATIONS       = 4096
+  FILE_CHUNK_LEN   = 65536
+
+  def self.getphrase(check=false)
+    begin
+      phrase = HighLine.new.ask('Passphrase: '){|q| q.echo = '*' ; q.overwrite = true }
+      return phrase unless check
+      tmp = HighLine.new.ask('Retype passphrase: '){|q| q.echo = '*' ; q.overwrite = true }
+      return phrase if tmp == phrase
+    rescue Interrupt
+      exit -1
+    end while true
+  end
+
+  def self.encrypt(file, passphrase=nil)
+    raise "Cannot encrypt non-existent file: #{file.inspect}" unless File.exist?(file)
+    raise "Cannot encrypt unreadable file: #{file.inspect}" unless File.readable?(file)
+    raise "Cannot encrypt unwritable file: #{file.inspect}" unless File.writable?(file)
+    passhash   = false
+    if File.exist?(file + PASSHASH_SUFFIX)
+      raise "Cannot read password hash temporary file: #{(file + PASSHASH_SUFFIX).inspect}" unless File.readable?(file + PASSHASH_SUFFIX)
+      raise "Password hash temporary file length is invalid: #{(file + PASSHASH_SUFFIX).inspect}" unless File.size(file + PASSHASH_SUFFIX) == SALT_LEN + HMAC_LEN
+      fp = File.open(file + PASSHASH_SUFFIX, File::RDONLY)
+      salt = fp.read(SALT_LEN)
+      passcheck = fp.read(HMAC_LEN)
+      loop do
+        passphrase = getphrase if passphrase.nil?
+        phash = hashpass(passphrase, salt)
+        break if passcheck == phash[1]
+        puts "*** ERROR: Passphrase mismatch. Try again, abort, or delete temporary file: #{file + PASSHASH_SUFFIX}"
+        passphrase = nil
+      end
+      passhash = true
+    elsif passphrase.nil?
+      puts "*** ALERT: Enter your NEW passphrase twice. DO NOT FORGET IT, or you may lose your data!"
+      passphrase = getphrase(true)
+    end
+
+    ## Use secure random data to populate salt, key, and IV:
+    salt      = SecureRandom.random_bytes(SALT_LEN)  ## Acquire some fresh salt
+    file_key  = SecureRandom.random_bytes(KEY_LEN)   ## Get some random key material
+    file_iv   = SecureRandom.random_bytes(IV_LEN)    ## And a random initialization vector
+
+    ## Encrypt the file key and IV using password-derived keying material:
+    keymaterial = PBKDF2.new do |p|
+      p.hash_function = HMAC_FUNC
+      p.password      = passphrase
+      p.salt          = salt
+      p.iterations    = ITERATIONS
+      p.key_length    = KEY_LEN + IV_LEN
+    end.bin_string
+    cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
+    cipher.encrypt
+    ## No padding required for this operation since the file key + IV is
+    ## an exact multiple of the cipher block length:
+    cipher.padding = 0
+    cipher.key     = keymaterial[0,KEY_LEN]
+    cipher.iv      = keymaterial[KEY_LEN,IV_LEN]
+    encrypted_keymaterial = cipher.update(file_key + file_iv) + cipher.final
+    encrypted_file_key = encrypted_keymaterial[0,KEY_LEN]
+    encrypted_file_iv  = encrypted_keymaterial[KEY_LEN,IV_LEN]
+
+    ## Open the plaintext file for reading (and later overwriting):
+    rfp = File.open(file, File::RDWR|File::EXCL)
+
+    ## Open a temporary ciphertext file for writing:
+    wfp = Tempfile.new(File.basename(rfp.path), File.dirname(rfp.path))
+
+    ## Write the salt and encrypted file key + IV and
+    ## temporarily fill the HMAC slot with zero-bytes:
+    wfp.write(salt + encrypted_file_key + encrypted_file_iv + (0.chr * HMAC_LEN))
+
+    ## Start the HMAC:
+    hmac = OpenSSL::HMAC.new(passphrase, HMAC_FUNC)
+    hmac << salt
+    hmac << encrypted_file_key
+    hmac << encrypted_file_iv
+
+    ## Encrypt file with file key + IV:
+    cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
+    cipher.encrypt
+    ## Encryption of file contents uses PCKS#5 padding which OpenSSL should
+    ## have enabled by default.  Nevertheless, we explicitly enable it here:
+    cipher.padding = 1
+    cipher.key     = file_key
+    cipher.iv      = file_iv
+    until rfp.eof?
+      data = rfp.read(FILE_CHUNK_LEN)
+      if data.bytesize > 0
+        data = cipher.update(data)
+        hmac << data
+        wfp.write(data)
+      end
+    end
+    data = cipher.final
+    if data.bytesize > 0
+      ## Save the last bit-o-data and update the HMAC:
+      wfp.write(data)
+      hmac << data
+    end
+
+    ## Write HMAC digest to file:
+    wfp.pos = SALT_LEN + KEY_LEN + IV_LEN
+    wfp.write(hmac.digest)
+
+    ## Overwrite the original plaintext file with zero bytes.
+    ## This adds a small measure of security against recovering
+    ## the original unencrypted contents.  It would likely be
+    ## better to overwrite the file multiple times with different
+    ## bit patterns, including one or more iterations using
+    ## high-quality random data.
+    rfp.seek(0,File::SEEK_END)
+    fsize = rfp.pos
+    rfp.pos = 0
+    while rfp.pos + FILE_CHUNK_LEN < fsize
+      rfp.write(0.chr * FILE_CHUNK_LEN)
+    end
+    rfp.write(0.chr * (fsize - rfp.pos)) if rfp.pos < fsize
+    rfp.close
+
+    ## Copy file ownership/permissions:
+    stat = File.stat(rfp.path)
+    wfp.chown(stat.uid, stat.gid)
+    wfp.chmod(stat.mode)
+
+    ## Close the ciphertext temporary file without deleting:
+    wfp.close(false)
+
+    ## Rename temporary file to permanent name:
+    File.rename(wfp.path, rfp.path)
+
+    ## Remove password hash temp. file:
+    File.delete(file + PASSHASH_SUFFIX) if passhash
+  end
+
+  def self.decrypt(file, passphrase=nil, notemp=true)
+    raise "Cannot decrypt non-existent file: #{file.inspect}" unless File.exist?(file)
+    raise "Cannot decrypt unreadable file: #{file.inspect}" unless File.readable?(file)
+    raise "Cannot decrypt unwritable file: #{file.inspect}" unless File.writable?(file)
+    fsize = File.size(file)
+    raise "File is not in valid encrypted format: #{file.inspect}" unless fsize > HEADER_LEN && (fsize - HEADER_LEN) % BLOCK_LEN == 0
+    salt = encrypted_file_key = encrypted_file_iv = nil
+    loop do
+      passphrase = getphrase if passphrase.nil?
+      fp = File.open(file, File::RDONLY)
+      salt               = fp.read(SALT_LEN)
+      encrypted_file_key = fp.read(KEY_LEN)
+      encrypted_file_iv  = fp.read(IV_LEN)
+      file_hmac          = fp.read(HMAC_LEN)
+      test_hmac = OpenSSL::HMAC.new(passphrase, HMAC_FUNC)
+      test_hmac << salt
+      test_hmac << encrypted_file_key
+      test_hmac << encrypted_file_iv
+      until fp.eof?
+        data = fp.read(FILE_CHUNK_LEN)
+        test_hmac << data unless data.bytesize == 0
+      end
+      fp.close
+      break if test_hmac.digest == file_hmac
+      puts "*** ERROR: Incorrect passphrase, or file is not encrypted. Try again or abort."
+      passphrase = nil
+    end
+
+    ## Extract and decrypt the encrypted file key + IV.
+    ## First, regenerate the password-based key material that encrypts the
+    ## file key + IV:
+    keymaterial = PBKDF2.new do |p|
+      p.hash_function = HMAC_FUNC
+      p.password      = passphrase
+      p.salt          = salt
+      p.iterations    = ITERATIONS
+      p.key_length    = KEY_LEN + IV_LEN
+    end.bin_string
+    cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
+    cipher.decrypt
+    cipher.padding = 0 ## No padding is required for this operation
+    cipher.key     = keymaterial[0,KEY_LEN]
+    cipher.iv      = keymaterial[KEY_LEN,IV_LEN]
+    ## Decrypt file key + IV:
+    keymaterial = cipher.update(encrypted_file_key + encrypted_file_iv) + cipher.final
+    file_key = keymaterial[0,KEY_LEN]
+    file_iv  = keymaterial[KEY_LEN,IV_LEN]
+
+    ## Decrypt file:
+    cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
+    cipher.decrypt
+    cipher.padding = 1 ## File contents use PCKS#5 padding,OpenSSL's default method
+    cipher.key     = file_key
+    cipher.iv      = file_iv
+
+    ## Open ciphertext file for reading:
+    rfp = File.open(file, File::RDONLY|File::EXCL)
+
+    ## Open a temporary plaintext file for writing:
+    wfp = Tempfile.new(File.basename(rfp.path), File.dirname(rfp.path))
+
+    ## Begin reading the ciphertext beyond the headers:
+    rfp.pos = HEADER_LEN  ## Skip headers
+    until rfp.eof?
+      data = rfp.read(FILE_CHUNK_LEN)
+      if data.bytesize > 0
+        data = cipher.update(data)
+        wfp.write(data)
+      end
+    end
+    data = cipher.final
+    wfp.write(data) if data.bytesize > 0
+
+    ## Close the ciphertext source file:
+    rfp.close
+
+    ## Copy file ownership/permissions:
+    stat = File.stat(rfp.path)
+    wfp.chown(stat.uid, stat.gid)
+    wfp.chmod(stat.mode)
+
+    ## Close the plaintext temporary file without deleting:
+    wfp.close(false)
+
+    ## Rename temporary file to permanent name:
+    File.rename(wfp.path, rfp.path)
+
+    unless notemp
+      ## Write password hash temp. file using PBKDF2 as an iterated hash of sorts of HMAC_LEN bytes:
+      File.open(file + PASSHASH_SUFFIX, File::WRONLY|File::EXCL|File::CREAT) {|f| f.write(hashpass(passphrase).join)}
+    end
+  end
+  
+  ## Use PBKDF2 as if it were a hash function with salt to generate a
+  ## next-to-impossible-to-reverse-or-deliberately-collide hash of the
+  ## supplied passphrase:
+  def self.hashpass(passphrase, salt=nil)
+    ## Grab a new chunk of secure random data if no salt was supplied:
+    salt = SecureRandom.random_bytes(SALT_LEN) if salt.nil?
+    hash = PBKDF2.new do |p|
+      p.hash_function = HMAC_FUNC
+      p.password      = passphrase
+      p.salt          = salt
+      p.iterations    = ITERATIONS
+      p.key_length    = HMAC_LEN
+    end.bin_string
+    [ salt, hash ]
+  end
+
+end

data/test/test_cli.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'digest/sha2'
+
+class FileSafeCLITest < Test::Unit::TestCase
+  FILESAFE = File.join(File.dirname(__FILE__), '..', 'bin', 'filesafe')
+  def setup
+    ## Create a temporary file:
+    @testfile = 'test.out'
+    @passphrase = 'this is the encryption passphrase'
+    File.open(@testfile,'w'){|f| f.puts "Test data"}
+
+    ## Save SHA256 digest of the file:
+    @plaintext_hash = file_hash(@testfile)
+    @plaintext_size = File.size(@testfile)
+  end
+
+  def file_hash(filename)
+    Digest::SHA256.hexdigest(File.open(filename, 'r'){|f| f.read})
+  end
+
+  def teardown
+    File.unlink(@testfile)
+  end
+
+  def test_cli
+    ## Encrypt file:
+    `#{FILESAFE} -e -p '#{@passphrase}' '#{@testfile}'`
+   
+    assert(file_hash(@testfile) != @plaintext_hash)
+    assert(File.size(@testfile) != @plaintext_size)
+
+    ## Decrypt file:
+    `#{FILESAFE} -d -n -p '#{@passphrase}' '#{@testfile}'`
+
+    assert(file_hash(@testfile) == @plaintext_hash)
+    assert(File.size(@testfile) == @plaintext_size)
+  end
+end
+

data/test/test_module.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'digest/sha2'
+require_relative '../lib/filesafe.rb'
+
+class FileSafeModuleTest < Test::Unit::TestCase
+  FILESAFE = File.join(File.dirname(__FILE__), '..', 'bin', 'filesafe')
+  def setup
+    ## Create a temporary file:
+    @testfile = 'test.out'
+    @passphrase = 'four score and seven years ago'
+    File.open(@testfile,'w'){|f| f.puts "Some more test data"}
+
+    ## Save SHA256 digest of the file:
+    @plaintext_hash = file_hash(@testfile)
+    @plaintext_size = File.size(@testfile)
+  end
+
+  def file_hash(filename)
+    Digest::SHA256.hexdigest(File.open(filename, 'r'){|f| f.read})
+  end
+
+  def teardown
+    File.unlink(@testfile)
+  end
+
+  def test_module
+    ## Encrypt file:
+    FileSafe.encrypt(@testfile, @passphrase)
+   
+    assert(file_hash(@testfile) != @plaintext_hash)
+    assert(File.size(@testfile) != @plaintext_size)
+
+    ## Decrypt file:
+    FileSafe.decrypt(@testfile, @passphrase, true)
+
+    assert(file_hash(@testfile) == @plaintext_hash)
+    assert(File.size(@testfile) == @plaintext_size)
+  end
+
+  def test_hashpass
+    pass = "When in the course of human events..."
+    salt = "01caf8e2e844a37810280f231f3059aca54e631528c1c57eb643df2c" +
+           "8c6c74bc4a6136784ecff873dcd09a80059f6e80"
+    goal = "6c726ee33ad9e171612d646403b3e01bba0451574cde9b0af90d957e" +
+           "1b33c0830db1ac63b986f755faa8b1e9a944dbf4c7086da2eae122c3" +
+           "9f42a359ef12536c"
+    salt = [salt].pack('H*')
+    goal = [goal].pack('H*')
+    hash = FileSafe.hashpass(pass, salt)
+    assert(hash[1] == goal)
+  end
+end
+

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
+  - 1
   - 0
-  - 0
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Aaron D. Gifford
@@ -60,6 +60,9 @@ files:
 - VERSION.txt
 - Rakefile
 - bin/filesafe
+- lib/filesafe.rb
+- test/test_module.rb
+- test/test_cli.rb
 has_rdoc: true
 homepage: http://www.aarongifford.com/computers/filesafe/
 licenses: []