archive-zip 0.1.1 → 0.2.0

data/MANIFEST

@@ -15,12 +15,13 @@ lib/archive/support/zlib.rb
 lib/archive/zip.rb
 lib/archive/zip/codec.rb
 lib/archive/zip/codec/deflate.rb
+lib/archive/zip/codec/null_encryption.rb
 lib/archive/zip/codec/store.rb
+lib/archive/zip/codec/traditional_encryption.rb
+lib/archive/zip/data_descriptor.rb
 lib/archive/zip/entry.rb
-lib/archive/zip/datadescriptor.rb
-lib/archive/zip/extrafield.rb
-lib/archive/zip/extrafield/extendedtimestamp.rb
-lib/archive/zip/extrafield/raw.rb
-lib/archive/zip/extrafield/unix.rb
 lib/archive/zip/error.rb
-test/test_archive.rb
+lib/archive/zip/extra_field.rb
+lib/archive/zip/extra_field/extended_timestamp.rb
+lib/archive/zip/extra_field/raw.rb
+lib/archive/zip/extra_field/unix.rb

data/NEWS

@@ -6,6 +6,16 @@ detailed information is available in the rest of the documentation.
 <b>NOTE:</b> Date stamps in the following entries are in YYYY/MM/DD format.
 
 
+== v0.2.0 (2008/08/06)
+
+* Traditional (weak) encryption is now supported.
+* Adding new encryption methods should be easier now.
+* Fixed a bug where the compression codec for an entry loaded from an archive
+  was not being recorded.
+* The _compression_codec_ attribute for Entry instances is now used instead of
+  the _codec_ attribute to access the compression codec of the entry.
+
+
 == v0.1.1 (2008/07/11)
 
 * Archive files are now closed when the Archive::Zip object is closed even when
@@ -15,15 +25,15 @@ detailed information is available in the rest of the documentation.
 
 == v0.1.0 (2008/07/10)
 
-* Initial release
-* Archive creation and extraction is supported with only a few lines of code
+* Initial release.
+* Archive creation and extraction is supported with only a few lines of code.
   (See README)
-* Archives can be updated "in place" or dumped out to other files or pipes
-* Files, symlinks, and directories are supported within archives
-* Unix permission/mode bits are supported
+* Archives can be updated "in place" or dumped out to other files or pipes.
+* Files, symlinks, and directories are supported within archives.
+* Unix permission/mode bits are supported.
 * Unix user and group ownerships are supported.
 * Unix last accessed and last modified times are supported.
 * Entry extension (AKA extra field) implementations can be added on the fly.
 * Unknown entry extension types are preserved during archive processing.
-* Deflate and Store compression codecs supported out of the box
-* More compression codecs can be added on the fly
+* Deflate and Store compression codecs are supported out of the box.
+* More compression codecs can be added on the fly.

data/README

@@ -56,6 +56,23 @@ Create a few archives:
     :path_prefix => 'a/b/c'
   )
 
+  # Add the contents of a_directory to example5.zip and encrypt Ruby source
+  # files.
+  require 'archive/zip/codec/null_encryption'
+  require 'archive/zip/codec/traditional_encryption'
+  Archive::Zip.archive(
+    'example5.zip',
+    'a_directory/.',
+    :encryption_codec => lambda do |entry|
+      if entry.file? and entry.zip_path =~ /\.rb$/ then
+        Archive::Zip::Codec::TraditionalEncryption
+      else
+        Archive::Zip::Codec::NullEncryption
+      end
+    end,
+    :password => 'seakrit'
+  )
+
   # Create a new archive which will be written to a pipe.
   # Assume $stdout is the write end a pipe.
   # (ruby example.rb | cat >example.zip)
@@ -93,6 +110,9 @@ Now extract those archives:
     :overwrite => :older
   )
 
+  # Extract example5.zip to a_destination, decrypting the contents.
+  Archive::Zip.extract('example5.zip', 'a_destination', :password => 'seakrit')
+
 
 == Features
 
@@ -107,6 +127,7 @@ Now extract those archives:
 9.  Unknown entry extension types are preserved during archive processing.
 10. The Deflate and Store compression codecs are supported out of the box.
 11. More compression codecs can be added on the fly.
+12. Traditional (weak) encryption is supported out of the box.
 
 
 == Known Bugs/Limitations
@@ -119,7 +140,7 @@ Now extract those archives:
 4.  Reading archives from non-seekable IO, such as pipes and sockets, is not
     supported.
 5.  MSDOS permission attributes are not supported.
-6.  Encryption is not supported.
+6.  Strong encryption is not supported.
 7.  Zip64 is not supported.
 8.  Digital signatures are not supported.
 

data/lib/archive/zip.rb

@@ -19,12 +19,12 @@ module Archive # :nodoc:
   # entries, directory entries, file entries, and symlink entries.  File and
   # directory accessed and modified times, POSIX permissions, and ownerships can
   # be archived and restored as well depending on platform support for such
-  # metadata.
+  # metadata.  Traditional (weak) encryption is also supported.
   #
-  # Zip64, digital signatures, and encryption are not supported.  ZIP archives
-  # can only be read from seekable kinds of IO, such as files; reading archives
-  # from pipes or any other non-seekable kind of IO is not supported.  However,
-  # writing to such IO objects <b><em>IS</em></b> supported.
+  # Zip64, digital signatures, and strong encryption are not supported.  ZIP
+  # archives can only be read from seekable kinds of IO, such as files; reading
+  # archives from pipes or any other non-seekable kind of IO is not supported.
+  # However, writing to such IO objects <b><em>IS</em></b> supported.
   class Zip
     include Enumerable
 
@@ -251,15 +251,24 @@ module Archive # :nodoc:
     #   from the archive and +false+ if it should be included.  <b>NOTE:</b> If
     #   a directory is excluded in this way, the <b>:recursion</b> option has no
     #   effect for it.
-    # <b>:ignore_error</b>::
-    #   When set to +false+ (the default), an error generated while creating an
-    #   archive entry for a file will be raised.  Otherwise, the bad file is
-    #   skipped.
+    # <b>:password</b>::
+    #   Specifies a proc, lambda, or a String.  If a proc or lambda is used, it
+    #   must take a single argument containing a zip entry and return a String
+    #   to be used as an encryption key for the entry.  If a String is used, it
+    #   will be used as an encryption key for all encrypted entries.
+    # <b>:on_error</b>::
+    #   Specifies a proc or lambda which is called when an exception is raised
+    #   during the archival of an entry.  It takes two arguments, a file path
+    #   and an exception object generated while attempting to archive the entry.
+    #   If <tt>:retry</tt> is returned, archival of the entry is attempted
+    #   again.  If <tt>:skip</tt> is returned, the entry is skipped.  Otherwise,
+    #   the exception is raised.
     # Any other options which are supported by Archive::Zip::Entry.from_file are
     # also supported.
     #
     # Raises Archive::Zip::IOError if called after #close.  Raises
-    # Archive::Zip::EntryError if the <b>:ignore_error</b> option is +false+ and
+    # Archive::Zip::EntryError if the <b>:on_error</b> option is either unset or
+    # indicates that the error should be raised and
     # Archive::Zip::Entry.from_file raises an error.
     #
     # == Example
@@ -333,7 +342,6 @@ module Archive # :nodoc:
       options[:directories]  = true  unless options.has_key?(:directories)
       options[:symlinks]     = false unless options.has_key?(:symlinks)
       options[:flatten]      = false unless options.has_key?(:flatten)
-      options[:ignore_error] = false unless options.has_key?(:ignore_error)
 
       # Flattening the directory structure implies that directories are skipped
       # and that the path prefix should be ignored.
@@ -364,10 +372,16 @@ module Archive # :nodoc:
                                   ! options[:symlinks]
             )
           )
-        rescue Zip::EntryError
-          # Ignore the error if requested.
-          if options[:ignore_error] then
-            next
+        rescue StandardError => error
+          unless options[:on_error].nil? then
+            case options[:on_error][path, error]
+            when :retry
+              retry
+            when :skip
+              next
+            else
+              raise
+            end
           else
             raise
           end
@@ -375,16 +389,22 @@ module Archive # :nodoc:
 
         # Skip this entry if so directed.
         if (zip_entry.symlink? && ! options[:symlinks]) ||
-           (! options[:exclude].nil? && options[:exclude].call(zip_entry)) then
+           (! options[:exclude].nil? && options[:exclude][zip_entry]) then
           next
         end
 
+        # Set the encryption key for the entry.
+        if options[:password].kind_of?(String) then
+          zip_entry.password = options[:password]
+        elsif ! options[:password].nil? then
+          zip_entry.password = options[:password][zip_entry]
+        end
+
         # Add entries for directories (if requested) and files/symlinks.
         if (! zip_entry.directory? || options[:directories]) then
           add_entry(zip_entry)
         end
 
-
         # Recurse into subdirectories (if requested).
         if zip_entry.directory? && options[:recursion] then
           archive(
@@ -436,6 +456,18 @@ module Archive # :nodoc:
     #   Specifies a proc or lambda which takes a single argument containing a
     #   zip entry and returns +true+ if the entry should be skipped during
     #   extraction and +false+ if it should be extracted.
+    # <b>:password</b>::
+    #   Specifies a proc, lambda, or a String.  If a proc or lambda is used, it
+    #   must take a single argument containing a zip entry and return a String
+    #   to be used as a decryption key for the entry.  If a String is used, it
+    #   will be used as a decryption key for all encrypted entries.
+    # <b>:on_error</b>::
+    #   Specifies a proc or lambda which is called when an exception is raised
+    #   during the extraction of an entry.  It takes two arguments, a zip entry
+    #   and an exception object generated while attempting to extract the entry.
+    #   If <tt>:retry</tt> is returned, extraction of the entry is attempted
+    #   again.  If <tt>:skip</tt> is returned, the entry is skipped.  Otherwise,
+    #   the exception is raised.
     # Any other options which are supported by Archive::Zip::Entry#extract are
     # also supported.
     #
@@ -522,23 +554,44 @@ module Archive # :nodoc:
         file_exists = File.exist?(file_path)
         file_mtime = File.mtime(file_path) if file_exists
 
-        # Skip this entry if so directed.
-        if (! file_exists && ! options[:create]) ||
-           (file_exists &&
-            (options[:overwrite] == :never ||
-             options[:overwrite] == :older && entry.mtime <= file_mtime)) ||
-           (! options[:exclude].nil? && options[:exclude].call(entry)) then
-          next
-        end
+        begin
+          # Skip this entry if so directed.
+          if (! file_exists && ! options[:create]) ||
+             (file_exists &&
+              (options[:overwrite] == :never ||
+               options[:overwrite] == :older && entry.mtime <= file_mtime)) ||
+             (! options[:exclude].nil? && options[:exclude][entry]) then
+            next
+          end
 
-        if entry.directory? then
-          # Record the directories as they are encountered.
-          directories << entry
-        elsif entry.file? || (entry.symlink? && options[:symlinks]) then
-          # Extract files and symlinks.
-          entry.extract(
-            options.merge(:file_path => file_path)
-          )
+          # Set the decryption key for the entry.
+          if options[:password].kind_of?(String) then
+            entry.password = options[:password]
+          elsif ! options[:password].nil? then
+            entry.password = options[:password][entry]
+          end
+
+          if entry.directory? then
+            # Record the directories as they are encountered.
+            directories << entry
+          elsif entry.file? || (entry.symlink? && options[:symlinks]) then
+            # Extract files and symlinks.
+            entry.extract(
+              options.merge(:file_path => file_path)
+            )
+          end
+        rescue StandardError => error
+          unless options[:on_error].nil? then
+            case options[:on_error][entry, error]
+            when :retry
+              retry
+            when :skip
+            else
+              raise
+            end
+          else
+            raise
+          end
         end
       end
 
@@ -546,9 +599,25 @@ module Archive # :nodoc:
         # Then extract the directory entries in depth first order so that time
         # stamps, ownerships, and permissions can be properly restored.
         directories.sort { |a, b| b.zip_path <=> a.zip_path }.each do |entry|
-          entry.extract(
-            options.merge(:file_path => File.join(destination, entry.zip_path))
-          )
+          begin
+            entry.extract(
+              options.merge(
+                :file_path => File.join(destination, entry.zip_path)
+              )
+            )
+          rescue StandardError => error
+            unless options[:on_error].nil? then
+              case options[:on_error][entry, error]
+              when :retry
+                retry
+              when :skip
+              else
+                raise
+              end
+            else
+              raise
+            end
+          end
         end
       end
 

data/lib/archive/zip/codec.rb

@@ -7,24 +7,45 @@ module Archive; class Zip
   # of Archive::Zip::Codec::Deflate and Archive::Zip::Codec::Store for details
   # on implementing custom codecs.
   module Codec
-    # A Hash mapping compression methods to codec implementations.  New codecs
-    # must add a mapping here when defined in order to be used.
-    CODECS = {}
+    # A Hash mapping compression methods to compression codec implementations.
+    # New compression codecs must add a mapping here when defined in order to be
+    # used.
+    COMPRESSION_CODECS = {}
 
-    # Returns a new codec instance based on _compression_method_ and
+    # A Hash mapping encryption methods to encryption codec implementations.
+    # New encryption codecs must add a mapping here when defined in order to be
+    # used.
+    ENCRYPTION_CODECS  = {}
+
+    # Returns a new compression codec instance based on _compression_method_ and
     # _general_purpose_flags_.
-    def self.create(compression_method, general_purpose_flags)
-      CODECS[compression_method].new(general_purpose_flags)
+    def self.create_compression_codec(compression_method, general_purpose_flags)
+      # Load the standard compression codecs.
+      require 'archive/zip/codec/deflate'
+      require 'archive/zip/codec/store'
+
+      codec = COMPRESSION_CODECS[compression_method].new(general_purpose_flags)
+      raise Zip::Error, 'unsupported compression codec' if codec.nil?
+      codec
     end
 
-    # Returns +true+ if _compression_method_ is mapped to a codec, +false+
-    # otherwise.
-    def self.supported?(compression_method)
-      CODECS.has_key?(compression_method)
+    # Returns a new encryption codec instance based on _general_purpose_flags_.
+    #
+    # <b>NOTE:</b> The signature of this method will have to change in order to
+    # support the strong encryption codecs.  This is intended to be an internal
+    # method anyway, so this fact should not cause major issues for users of
+    # this library.
+    def self.create_encryption_codec(general_purpose_flags)
+      general_purpose_flags &= 0b0000000001000001
+      if general_purpose_flags == 0b0000000000000000 then
+        require 'archive/zip/codec/null_encryption'
+        codec = NullEncryption.new
+      elsif general_purpose_flags == 0b0000000000000001 then
+        require 'archive/zip/codec/traditional_encryption'
+        codec = TraditionalEncryption.new
+      end
+      raise Zip::Error, 'unsupported encryption codec' if codec.nil?
+      codec
     end
   end
 end; end
-
-# Load the standard codecs.
-require 'archive/zip/codec/deflate'
-require 'archive/zip/codec/store'

data/lib/archive/zip/codec/deflate.rb

@@ -1,21 +1,21 @@
 require 'archive/support/zlib'
 require 'archive/zip/codec'
-require 'archive/zip/datadescriptor'
+require 'archive/zip/data_descriptor'
 
 module Archive; class Zip; module Codec
-  # Archive::Zip::Codec::Deflate is a handle for the deflate-inflate codec as
-  # defined in Zlib which provides convenient interfaces for writing and reading
-  # deflated streams.
+  # Archive::Zip::Codec::Deflate is a handle for the deflate-inflate codec
+  # as defined in Zlib which provides convenient interfaces for writing and
+  # reading deflated streams.
   class Deflate
-    # Archive::Zip::Codec::Deflate::Deflate extends Zlib::ZWriter in order to
+    # Archive::Zip::Codec::Deflate::Compress extends Zlib::ZWriter in order to
     # specify the standard Zlib options required by ZIP archives and to provide
-    # a close method which can optionally close the delegate IO-like object.  In
-    # addition a convenience method is provided for generating DataDescriptor
+    # a close method which can optionally close the delegate IO-like object.
+    # In addition a convenience method is provided for generating DataDescriptor
     # objects based on the data which is passed through this object.
     #
     # Instances of this class should only be accessed via the
     # Archive::Zip::Codec::Deflate#compressor method.
-    class Deflate < Zlib::ZWriter
+    class Compress < Zlib::ZWriter
       # Creates a new instance of this class with the given arguments using #new
       # and then passes the instance to the given block.  The #close method is
       # guaranteed to be called after the block completes.
@@ -61,15 +61,15 @@ module Archive; class Zip; module Codec
       end
     end
 
-    # Archive::Zip::Codec::Deflate::Inflate extends Zlib::ZReader in order to
+    # Archive::Zip::Codec::Deflate::Decompress extends Zlib::ZReader in order to
     # specify the standard Zlib options required by ZIP archives and to provide
-    # a close method which can optionally close the delegate IO-like object.  In
-    # addition a convenience method is provided for generating DataDescriptor
+    # a close method which can optionally close the delegate IO-like object.
+    # In addition a convenience method is provided for generating DataDescriptor
     # objects based on the data which is passed through this object.
     #
     # Instances of this class should only be accessed via the
     # Archive::Zip::Codec::Deflate#decompressor method.
-    class Inflate < Zlib::ZReader
+    class Decompress < Zlib::ZReader
       # Creates a new instance of this class with the given arguments using #new
       # and then passes the instance to the given block.  The #close method is
       # guaranteed to be called after the block completes.
@@ -112,11 +112,12 @@ module Archive; class Zip; module Codec
       end
     end
 
-    # The numeric identifier assigned to this codec by the ZIP specification.
+    # The numeric identifier assigned to this compression codec by the ZIP
+    # specification.
     ID = 8
 
-    # Register this codec.
-    CODECS[ID] = self
+    # Register this compression codec.
+    COMPRESSION_CODECS[ID] = self
 
     # A bit mask used to denote that Zlib's default compression level should be
     # used.
@@ -131,7 +132,7 @@ module Archive; class Zip; module Codec
     SUPER_FAST = 0b110
 
     # This method signature is part of the interface contract expected by
-    # Archive::Zip::Entry for codec objects.
+    # Archive::Zip::Entry for compression codec objects.
     #
     # Creates a new instance of this class using bits 1 and 2 of
     # _general_purpose_flags_ to select a compression level to be used by
@@ -155,45 +156,46 @@ module Archive; class Zip; module Codec
     end
 
     # This method signature is part of the interface contract expected by
-    # Archive::Zip::Entry for codec objects.
+    # Archive::Zip::Entry for compression codec objects.
     #
-    # A convenience method for creating an Archive::Zip::Codec::Deflate::Deflate
-    # object using that class' open method.  The compression level for the open
-    # method is pulled from the value of the _general_purpose_flags_ argument of
-    # new.
+    # A convenience method for creating an
+    # Archive::Zip::Codec::Deflate::Compress object using that class' open
+    # method.  The compression level for the open method is pulled from the
+    # value of the _general_purpose_flags_ argument of new.
     def compressor(io, &b)
-      Deflate.open(io, @zlib_compression_level, &b)
+      Compress.open(io, @zlib_compression_level, &b)
     end
 
     # This method signature is part of the interface contract expected by
-    # Archive::Zip::Entry for codec objects.
+    # Archive::Zip::Entry for compression codec objects.
     #
-    # A convenience method for creating an Archive::Zip::Codec::Deflate::Inflate
-    # object using that class' open method.
+    # A convenience method for creating an
+    # Archive::Zip::Codec::Deflate::Decompress object using that class' open
+    # method.
     def decompressor(io, &b)
-      Inflate.open(io, &b)
+      Decompress.open(io, &b)
     end
 
     # This method signature is part of the interface contract expected by
-    # Archive::Zip::Entry for codec objects.
+    # Archive::Zip::Entry for compression codec objects.
     #
     # Returns an integer which indicates the version of the official ZIP
-    # specification which introduced support for this codec.
+    # specification which introduced support for this compression codec.
     def version_needed_to_extract
       0x0014
     end
 
     # This method signature is part of the interface contract expected by
-    # Archive::Zip::Entry for codec objects.
+    # Archive::Zip::Entry for compression codec objects.
     #
-    # Returns an integer used to flag that this codec is used for a particular
-    # ZIP archive entry.
+    # Returns an integer used to flag that this compression codec is used for a
+    # particular ZIP archive entry.
     def compression_method
       ID
     end
 
     # This method signature is part of the interface contract expected by
-    # Archive::Zip::Entry for codec objects.
+    # Archive::Zip::Entry for compression codec objects.
     #
     # Returns an integer representing the general purpose flags of a ZIP archive
     # entry where bits 1 and 2 are set according to the compression level