filesafe 1.1.0 → 2.0.1

data/README.txt

@@ -46,12 +46,26 @@ 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.
+A new file is opened, and SALT + C_F_KEY + C_F_IV are written.  A number
+of zero bytes are written to make space to store the HMAC that will be
+calculated.
 
-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.
+Then the contents of the plaintext file are then encrypted using F_KEY and F_IV
+and written to the new file following the file header described above.
+
+A HMAC is calculated on SALT + C_F_KEY + C_F_IV + encrypted file text.
+Then the PBKDF2 function is applied to PASS + HMAC using the same SALT
+to provide a MAC of sorts.
+
+The HMAC isn't used directly because it would be easier to attempt to
+apply a dictionary attack against the passphrase, at least for smaller
+encrypted files, without PBKDF2's multiple iterations which increase
+computation time for each passphrase guess.  This new HMAC/PBKDF2 hybrid
+MAC is written over the top of the zero-bytes previously allocated, and
+the file is closed.
+
+Version 1.x of this library and utility stored the HMAC directly instead
+utilizing this hybrid MAC scheme.
 
 This new file is the encrypted file.  The old plaintext file is overwritten and
 removed.
@@ -59,16 +73,32 @@ 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.
+To recover the file, an HMAC is calculated on the encrypted file contents,
+excluding the HMAC/PBKDF2 hybrid MAC data.  The PBKDF2 function is applied
+supplying PASS + HMAC as the passphrase and the SALT from the file to
+calculate the hybrid HMAC/PBKDF2 MAC.  This hybrid MAC is then compared to
+the one from the encrypted file.  If the calculated MAC doesn't match the
+supplied MAC, then either the file has been corrupted, or the passphrase
+is incorrect.
+
+If the MACs match, the encrypted master key material C_F_KEY and C_F_IV
+are read from the file.  M_KEY and M_IV are generated using PBKDF2
+and PASS with SALT.  F_KEY and F_IV are decrypted using M_KEY and M_IV.
+With the file encryption key and initialization vector, the file contents
+are then decrypted, revealing the original file plaintext.
+
+The encrypted file can then be safely removed.  The provided utility has
+the option of then creating a separate file containing a newly-generated
+salt and a PBKDF2 generated sum using the new salt and the original
+passphrase.  This provides the user the ability to ask for a passphrase
+and compare it (using PBKDF2 and the salt) to the original passphrase
+without revealing the original passphrase.
+
+The filesafe utility by default does exactly this, so that if a file
+is re-encrypted (which will always use a freshly generated salt and
+key), the user is asked for the original passphrase once again.  Should
+the user decide to use a new phrase, the temporary file may be safely
+deleted.
 
 
 LICENSE
@@ -102,8 +132,11 @@ Please report bugs by going to the author's web site and clicking on the
 
 * http://www.aarongifford.com/leaveanote.html
 
-
-
-Thank you!
--- Aaron D. Gifford
+I am debating as to whether I should replace the HMAC in the file header
+with a PBKDF2 function, perhaps PBKDF2(passphrase, iterations, HMAC)
+so as to make dictionary attacks against passwords much more difficult.
+It would result in a slight file format change, so I'd have to bump up
+the version, and perhaps provide a fallback to the old method if a
+passphrase doesn't seem to match a ciphertext file's stored PBKDF2
+result.
 

data/Rakefile

@@ -10,8 +10,9 @@ gemspec = Gem::Specification.new do |spec|
   spec.homepage     = 'http://www.aarongifford.com/computers/filesafe/'
   spec.summary      = 'Encrypt/decrypt files with a random 256-bit AES key secured by a passphrase derived master key using PBKDF2'
   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.has_rdoc     = true ## Very limited documentation
   spec.extra_rdoc_files = [ 'README.txt' ]
+  spec.require_paths = [ 'lib' ]
   spec.files = FileList[
     'README.txt',
     'VERSION.txt',
@@ -34,7 +35,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.name     = 'rdoc'
   rdoc.main     = 'README.txt'
   rdoc.rdoc_dir = 'doc'
-  rdoc.rdoc_files.include('README.txt')
+  rdoc.rdoc_files.include('README.txt', 'lib/*')
 end
 
 Rake::TestTask.new do |t|

data/VERSION.txt

@@ -1 +1 @@
-1.1.0
+2.0.1

data/bin/filesafe

@@ -1,15 +1,14 @@
 #!/usr/bin/env ruby
 #
-# FileSafe
-# Version: 1.1.0
-# From:    http://www.aarongifford.com/computers/filesafe/index.html
+# FileSafe - http://www.aarongifford.com/computers/filesafe/
 #
 # A simple file encryption/decryption script that uses 256-bit AES encryption,
 # a secure random number/data source, and the password/passphrase (via PBKDF2)
 # to encrypt/decrypt one or more files.
 #
-# Written by Aaron D. Gifford - http://www.aarongifford.com/
-# Copyright (c) 2010 Aaron D. Gifford
+# Author::    Aaron D. Gifford - http://www.aarongifford.com/
+# Copyright:: Copyright (c) 2010 Aaron D. Gifford
+# License::   This file may be used and distributed under the MIT license
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -39,14 +38,16 @@ Usage: #{$0} -e|-d [-n] [-p 'pass phrase'] [--] file [file [file...]]
   -e                Encrypt file(s)
   -d                Decrypt file(s)
   -p 'pass phrase'  Passphrase to use for operation
-  -n                Do NOT create a temporary password HMAC/hash file (during decryption)
+  -n                Do NOT use a temporary password HMAC/hash file:
+                     * ignore such file if found during encryption
+                     * do not create such file during decryption
   --                End of options -- all subsequent arguments are files
 
   EOM
   exit
 end
 
-opt = {}
+opt = { :notemp => false }
 while ARGV.size > 0 && ARGV[0][0,1] == '-'
   case ARGV[0]
   when '-e'
@@ -63,7 +64,6 @@ while ARGV.size > 0 && ARGV[0][0,1] == '-'
     opt[:phrase] = ARGV.shift
   when '-n'
     ARGV.shift
-    usage "This option only applies to decryption operations." unless opt[:op] == :decrypt
     opt[:notemp] = true
   when '--'
     break
@@ -80,7 +80,7 @@ ARGV.each do |file|
       FileSafe.decrypt(file, opt[:phrase], opt[:notemp])
       puts "FILE DECRYPTED: #{file}"
     else
-      FileSafe.encrypt(file, opt[:phrase])
+      FileSafe.encrypt(file, opt[:phrase], opt[:notemp])
       puts "ENCRYPTED: #{file}"
     end
   rescue StandardError => e

data/lib/filesafe.rb

@@ -1,5 +1,35 @@
 #!/usr/bin/env ruby
+#
+# FileSafe - http://www.aarongifford.com/computers/filesafe/
+#
+# A simple file encryption/decryption script that uses 256-bit AES encryption,
+# a secure random number/data source, and the password/passphrase (via PBKDF2)
+# to encrypt/decrypt one or more files.
+#
+# Author::    Aaron D. Gifford - http://www.aarongifford.com/
+# Copyright:: Copyright (c) 2010 Aaron D. Gifford
+# License::   This file may be used and distributed under the MIT license
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
 
+# FileSafe module has four module methods, two for file encryption/decryption,
+# one for passphrase hashing, and one for reading a passphrase from a terminal.
 module FileSafe
   require 'openssl'       ## Encryption/HMAC/Hash algorithms
   require 'securerandom'  ## Cryptographically secure source of random data
@@ -7,20 +37,42 @@ module FileSafe
   require 'highline'      ## For reading a passphrase from a terminal
   require 'tempfile'      ## Temporary file creation
 
-  ## CONFIGURATION ITEMS:
+  # Temporary passphrase hash file suffix:
   PASSHASH_SUFFIX  = '.pass'
+
+  # Default cipher (AES-256 in CBC mode):
   CIPHER           = 'aes-256-cbc'
+
   cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
+
+  # Cipher block length/size (128 bits/16 bytes for AES-256):
   BLOCK_LEN        = cipher.block_size
+
+  # Cipher key length (256 bits/32 bytes for AES-256):
   KEY_LEN          = cipher.key_len
+
+  # Cipher initialization vector (IV) length (128 bits/16 bytes for AES-256):
   IV_LEN           = cipher.iv_len
+
+  # Salt size/length (384 bits/48 bytes, KEY + IV size):
   SALT_LEN         = KEY_LEN + IV_LEN
+
+  # Default hash function to use for HMAC (SHA-512 by default):
   HMAC_FUNC        = 'sha512'
+
+  # Default HMAC size/length (512 bits/64 bytes for HMAC-SHA-512):
   HMAC_LEN         = OpenSSL::HMAC.new('', HMAC_FUNC).digest.bytesize
+
+  # Default ciphertext file header size (key + IV + salt + HMAC = 1280 bits/160 bytes by default) 
   HEADER_LEN       = KEY_LEN + IV_LEN + SALT_LEN + HMAC_LEN
+
+  # Number of iterations to use in PBKDF2 (4096 by default):
   ITERATIONS       = 4096
+
+  # Number of bytes to read from plaintext/ciphertext files at a time (64KB by default): 
   FILE_CHUNK_LEN   = 65536
 
+  # Read a passphrase from a terminal.
   def self.getphrase(check=false)
     begin
       phrase = HighLine.new.ask('Passphrase: '){|q| q.echo = '*' ; q.overwrite = true }
@@ -32,25 +84,43 @@ module FileSafe
     end while true
   end
 
-  def self.encrypt(file, passphrase=nil)
+  def self.passmatch?(passphrase, salt, hash)
+    pbkdf2(passphrase, salt, HMAC_LEN) == hash
+  end
+
+  # Encrypt a file with the supplied passphrase--or if none is supplied,
+  # read a passphrase from the terminal.
+  def self.encrypt(file, passphrase=nil, notemp=true)
     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)
+    if !notemp && 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
+
+      ## Read temporary passphrase hash file:
+      psalt = pcheck = nil
+      File.open(file + PASSHASH_SUFFIX, File::RDONLY) do |fp|
+        psalt  = fp.read(SALT_LEN)
+        pcheck = fp.read(HMAC_LEN)
+      end
+
+      ## Was a passphrase supplied?
+      if passphrase.nil?
+        ## No, so ask for one:
+        loop do
+          passphrase = getphrase
+          ## Check the phrase against the stored hash:
+          break if passmatch?(passphrase, psalt, pcheck)
+          puts "*** ERROR: Passphrase mismatch. Try again, abort, or delete temporary file: #{file + PASSHASH_SUFFIX}"
+        end
+      else
+        ## Yes, so check supplied phrase against the stored hash:
+        raise "Passphrase mismatch" unless passmatch?(passphrase, psalt, pcheck)
+      end
     elsif passphrase.nil?
       puts "*** ALERT: Enter your NEW passphrase twice. DO NOT FORGET IT, or you may lose your data!"
       passphrase = getphrase(true)
@@ -62,13 +132,7 @@ module FileSafe
     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
+    keymaterial = pbkdf2(passphrase, salt, KEY_LEN + IV_LEN)
     cipher = OpenSSL::Cipher::Cipher.new(CIPHER)
     cipher.encrypt
     ## No padding required for this operation since the file key + IV is
@@ -87,7 +151,7 @@ module FileSafe
     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:
+    ## temporarily fill the PBKDF2-hashed HMAC slot with zero-bytes:
     wfp.write(salt + encrypted_file_key + encrypted_file_iv + (0.chr * HMAC_LEN))
 
     ## Start the HMAC:
@@ -119,9 +183,11 @@ module FileSafe
       hmac << data
     end
 
-    ## Write HMAC digest to file:
+    ## Instead of storing the HMAC directly, use PBKDF2 to store data generated
+    ## from the HMAC in hopes that PBKDF2's multiple iterations will make
+    ## brute force dictionary attacks against the passphrase much more cumbersome:
     wfp.pos = SALT_LEN + KEY_LEN + IV_LEN
-    wfp.write(hmac.digest)
+    wfp.write(pbkdf2(passphrase + hmac.digest, salt, HMAC_LEN))
 
     ## Overwrite the original plaintext file with zero bytes.
     ## This adds a small measure of security against recovering
@@ -153,6 +219,10 @@ module FileSafe
     File.delete(file + PASSHASH_SUFFIX) if passhash
   end
 
+  # Decrypt a file with the supplied passphrase--or if none is supplied,
+  # read a passphrase from the terminal. Optionally create a temporary
+  # file of the same name with a suffix (by default ".pass") and store
+  # a passphrase hash in that file for future use.
   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)
@@ -166,7 +236,7 @@ module FileSafe
       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)
+      file_check         = fp.read(HMAC_LEN)
       test_hmac = OpenSSL::HMAC.new(passphrase, HMAC_FUNC)
       test_hmac << salt
       test_hmac << encrypted_file_key
@@ -176,7 +246,7 @@ module FileSafe
         test_hmac << data unless data.bytesize == 0
       end
       fp.close
-      break if test_hmac.digest == file_hmac
+      break if pbkdf2(passphrase + test_hmac.digest, salt, HMAC_LEN) == file_check
       puts "*** ERROR: Incorrect passphrase, or file is not encrypted. Try again or abort."
       passphrase = nil
     end
@@ -242,24 +312,24 @@ module FileSafe
 
     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)}
+      salt = SecureRandom.random_bytes(SALT_LEN) if salt.nil?
+      File.open(file + PASSHASH_SUFFIX, File::WRONLY|File::EXCL|File::CREAT) do |f|
+        f.write(salt + pbkdf2(passphrase, salt, HMAC_LEN))
+      end
     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?
+  # Execute PBKDF2 to generate the specified number of bytes of
+  # pseudo-random key material.
+  def self.pbkdf2(passphrase, salt, len)
     hash = PBKDF2.new do |p|
       p.hash_function = HMAC_FUNC
       p.password      = passphrase
       p.salt          = salt
       p.iterations    = ITERATIONS
-      p.key_length    = HMAC_LEN
+      p.key_length    = len
     end.bin_string
-    [ salt, hash ]
   end
 
 end
+

data/test/bar

@@ -0,0 +1 @@
+foo

data/test/test_decrypt.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require_relative '../lib/filesafe.rb'
+
+class FileSafeDecryptTest < Test::Unit::TestCase
+  CIPHERTEXT = [
+    "60e8aacea874e36f39fef5f51cf727252359c575230b7306b6379194" +
+    "12bc53e9106ddaecc0ded13503e6ef9d3ff9f0285bb133d3d88464c0" +
+    "eea4f728ae509942a4e8be070a70d49b8668ddbda2102412ca42c917" +
+    "bd74c824ae6b35bb697a0fccd8f0822e310f96bfc34546e289e6dbed" +
+    "f3dd30eca6585ad344593ca65f6aa323722a29c1c19257b135756340" +
+    "7a88de6a92a85dae5dd9ea0cb8a2ccaf3c45bace571cb0c791186837" +
+    "a3a6ff650545286afbd75087b42582da571521fbc74fa3499dc22ebc" +
+    "8482e13c4055313b38a0cf79"].pack('H*')
+  PLAINTEXT = 
+    "This is a PLAINTEXT file for testing\n"
+  PASS      =
+    "topsecretstuff"
+
+  def setup
+    ## Create a temporary file:
+    @testfile = 'test.out'
+    File.open(@testfile,'w'){|f| f.print CIPHERTEXT }
+  end
+
+  def teardown
+    File.unlink(@testfile)
+  end
+
+  def test_decrypt
+    ## Decrypt data:
+    FileSafe.decrypt(@testfile, PASS, true)
+
+    ## Read decrypted file contents:
+    plaintext = File.open(@testfile,'r'){|f| f.read}
+
+    assert(PLAINTEXT == plaintext)
+  end
+end
+

data/test/test_module.rb

@@ -39,7 +39,7 @@ class FileSafeModuleTest < Test::Unit::TestCase
     assert(File.size(@testfile) == @plaintext_size)
   end
 
-  def test_hashpass
+  def test_pbkdf2
     pass = "When in the course of human events..."
     salt = "01caf8e2e844a37810280f231f3059aca54e631528c1c57eb643df2c" +
            "8c6c74bc4a6136784ecff873dcd09a80059f6e80"
@@ -48,8 +48,8 @@ class FileSafeModuleTest < Test::Unit::TestCase
            "9f42a359ef12536c"
     salt = [salt].pack('H*')
     goal = [goal].pack('H*')
-    hash = FileSafe.hashpass(pass, salt)
-    assert(hash[1] == goal)
+    hash = FileSafe.pbkdf2(pass, salt, FileSafe::HMAC_LEN)
+    assert(hash == goal)
   end
 end
 

metadata

@@ -3,10 +3,10 @@ name: filesafe
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 1
-  - 1
+  - 2
   - 0
-  version: 1.1.0
+  - 1
+  version: 2.0.1
 platform: ruby
 authors: 
 - Aaron D. Gifford
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-30 00:00:00 -07:00
+date: 2011-01-04 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -61,7 +61,9 @@ files:
 - Rakefile
 - bin/filesafe
 - lib/filesafe.rb
+- test/bar
 - test/test_module.rb
+- test/test_decrypt.rb
 - test/test_cli.rb
 has_rdoc: true
 homepage: http://www.aarongifford.com/computers/filesafe/