hexapdf 0.1.0

data/lib/hexapdf/document_utils.rb

@@ -0,0 +1,209 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'hexapdf/configuration'
+
+module HexaPDF
+
+  # This class provides utility functions for PDF documents. It is available through the
+  # HexaPDF::Document#utils method.
+  #
+  # Some functions can't be attributed to a single "manager" object. For example, while embedding a
+  # file can be done within a HexaPDF::Type::Filespecification object, loading an image from a file
+  # as a PDF object doesn't have such a place. Such functions are available via this class.
+  class DocumentUtils
+
+    # This module provides methods for managing the images embedded in a PDF file; images
+    # themselves are represented by the HexaPDF::Type::Image class.
+    #
+    # Since an image can be used as a mask for another image, not all image objects found in a PDF
+    # are really used as images. Such cases are all handled by this class automatically.
+    module Images
+
+      # :call-seq:
+      #   images.add_image(file)            -> image
+      #   images.add_image(io)              -> image
+      #
+      # Adds the image from the given file or IO to the PDF and returns the image object.
+      #
+      # If the image has been added to the PDF before (i.e. if there is an image object with the
+      # same path name), the already existing image object is returned.
+      def add_image(file_or_io)
+        name = if file_or_io.kind_of?(String)
+                 file_or_io
+               elsif file_or_io.respond_to?(:to_path)
+                 file_or_io.to_path
+               end
+        if name
+          name = File.absolute_path(name)
+          image = each_image.find {|im| im.source_path == name}
+        end
+        unless image
+          image = image_loader_for(file_or_io).load(@document, file_or_io)
+          image.source_path = name
+        end
+        image
+      end
+
+      # :call-seq:
+      #   images.each_image {|image| block }   -> images
+      #   images.each_image                    -> Enumerator
+      #
+      # Iterates over all images in the PDF.
+      #
+      # Note that only real images are yielded which means, for example, that images used as soft
+      # mask are not.
+      def each_image(&block)
+        images = @document.each(current: false).select do |obj|
+          obj[:Subtype] == :Image && !obj[:ImageMask]
+        end
+        masks = images.each_with_object([]) do |image, temp|
+          temp << image[:Mask] if image[:Mask].kind_of?(Stream)
+          temp << image[:SMask] if image[:SMask].kind_of?(Stream)
+        end
+        (images - masks).each(&block)
+      end
+
+      private
+
+      # Returns the image loader (see ImageLoader) for the given file or IO stream or raises an
+      # error if no suitable image loader is found.
+      def image_loader_for(file_or_io)
+        GlobalConfiguration['image_loader'].each_index do |index|
+          loader = GlobalConfiguration.constantize('image_loader', index) do
+            raise HexaPDF::Error, "Couldn't retrieve image loader from configuration"
+          end
+          return loader if loader.handles?(file_or_io)
+        end
+
+        raise HexaPDF::Error, "Couldn't find suitable image loader"
+      end
+
+    end
+
+
+    # This module provides methods for managing file specification of a PDF file.
+    #
+    # Note that for a given PDF file not all file specifications may be found, e.g. when a file
+    # specification is only a string. Therefore this module can only handle those file
+    # specifications that are indirect file specification dictionaries with the /Type key set.
+    module Files
+
+      # :call-seq:
+      #   files.add_file(filename, name: File.basename(filename), description: nil, embed: true) -> file_spec
+      #   files.add_file(io, name:, description: nil)                      -> file_spec
+      #
+      # Adds the file or IO to the PDF and returns the corresponding file specification object.
+      #
+      # Options:
+      #
+      # name::
+      #     The name that should be used for the file path. This name is also for registering the
+      #     file in the EmbeddedFiles name tree.
+      #
+      # description::
+      #     A description of the file.
+      #
+      # embed::
+      #     When an IO object is given, it is always embedded and this option is ignored.
+      #
+      #     When a filename is given and this option is +true+, then the file is embedded. Otherwise
+      #     only a reference to it is stored.
+      #
+      # See: HexaPDF::Type::FileSpecification
+      def add_file(file_or_io, name: nil, description: nil, embed: true)
+        name ||= File.basename(file_or_io) if file_or_io.kind_of?(String)
+        if name.nil?
+          raise ArgumentError, "The name argument is mandatory when given an IO object"
+        end
+
+        spec = @document.add(Type: :Filespec)
+        spec.path = name
+        spec[:Desc] = description if description
+        spec.embed(file_or_io, name: name, register: true) if embed || !file_or_io.kind_of?(String)
+        spec
+      end
+
+      # :call-seq:
+      #   files.each_file(search: false) {|file_spec| block }   -> files
+      #   files.each_file(search: false)                        -> Enumerator
+      #
+      # Iterates over indirect file specification dictionaries of the PDF.
+      #
+      # By default, only the file specifications in their standard locations, namely in the
+      # EmbeddedFiles name tree and in the page annotations, are returned. If the +search+ option is
+      # +true+, then all indirect objects are searched for file specification dictionaries which is
+      # much slower.
+      def each_file(search: false)
+        return to_enum(__method__, search: search) unless block_given?
+
+        if search
+          @document.each(current: false) do |obj|
+            yield(obj) if obj.type == :Filespec
+          end
+        else
+          seen = {}
+          tree = @document.catalog[:Names] && @document.catalog[:Names][:EmbeddedFiles]
+          tree.each_entry do |_, spec|
+            seen[spec] = true
+            yield(spec)
+          end if tree
+
+          @document.pages.each_page do |page|
+            next unless page[:Annots]
+            page[:Annots].each do |annot|
+              annot = @document.deref(annot)
+              next unless annot[:Subtype] == :FileAttachment
+              spec = @document.deref(annot[:FS])
+              yield(spec) unless seen.key?(spec)
+              seen[spec] = true
+            end
+          end
+        end
+
+        self
+      end
+
+    end
+
+    include Images
+    include Files
+
+    # Creates a new DocumentUtils object for the given PDF document.
+    def initialize(document)
+      @document = document
+    end
+
+  end
+
+end

data/lib/hexapdf/encryption/aes.rb

@@ -0,0 +1,206 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'securerandom'
+require 'hexapdf/error'
+
+module HexaPDF
+  module Encryption
+
+    # Common interface for AES algorithms
+    #
+    # This module defines the common interface that is used by the security handlers to encrypt or
+    # decrypt data with AES. It has to be *prepended* by any AES algorithm class.
+    #
+    # See the ClassMethods module for available class level methods of AES algorithms.
+    #
+    # == Implementing an AES Class
+    #
+    # An AES class needs to define at least the following methods:
+    #
+    # initialize(key, iv, mode)::
+    #   Initializes the AES algorithm with the given key and initialization vector. The mode
+    #   determines how the AES algorithm object works: If the mode is :encrypt, the object
+    #   encrypts the data, if the mode is :decrypt, the object decrypts the data.
+    #
+    # process(data)::
+    #   Processes the data and returns the encrypted/decrypted data. The method can assume that
+    #   the passed in data always has a length that is a multiple of BLOCK_SIZE.
+    module AES
+
+      # Valid AES key lengths
+      VALID_KEY_LENGTH = [16, 24, 32]
+
+      # The AES block size
+      BLOCK_SIZE = 16
+
+      # Convenience methods for decryption and encryption that operate according to the PDF
+      # specification.
+      #
+      # These methods will be available on the class object that prepends the AES module.
+      module ClassMethods
+
+        # Encrypts the given +data+ using the +key+ and a randomly generated initialization
+        # vector.
+        #
+        # The data is padded using the PKCS#5 padding scheme and the initialization vector is
+        # prepended to the encrypted data,
+        #
+        # See: PDF1.7 s7.6.2.
+        def encrypt(key, data)
+          iv = random_bytes(BLOCK_SIZE)
+          iv << new(key, iv, :encrypt).process(pad(data))
+        end
+
+        # Returns a Fiber object that encrypts the data from the given source fiber with the
+        # +key+.
+        #
+        # Padding and the initialization vector are handled like in #encrypt.
+        def encryption_fiber(key, source)
+          Fiber.new do
+            data = random_bytes(BLOCK_SIZE)
+            algorithm = new(key, data, :encrypt)
+            Fiber.yield(data)
+
+            data = ''.b
+            while source.alive? && (new_data = source.resume)
+              data << new_data
+              next if data.length < BLOCK_SIZE
+              new_data = data.slice!(0, data.length - data.length % BLOCK_SIZE)
+              Fiber.yield(algorithm.process(new_data))
+            end
+
+            algorithm.process(pad(data))
+          end
+        end
+
+        # Decrypts the given +data+ using the +key+.
+        #
+        # It is assumed that the initialization vector is included in the first BLOCK_SIZE bytes
+        # of the data. After the decryption the PKCS#5 padding is removed.
+        #
+        # See: PDF1.7 s7.6.2.
+        def decrypt(key, data)
+          if data.length % BLOCK_SIZE != 0 || data.length < 2 * BLOCK_SIZE
+            raise HexaPDF::EncryptionError, "Invalid data for decryption, need 32 + 16*n bytes"
+          end
+          unpad(new(key, data.slice!(0, BLOCK_SIZE), :decrypt).process(data))
+        end
+
+        # Returns a Fiber object that decrypts the data from the given source fiber with the
+        # +key+.
+        #
+        # Padding and the initialization vector are handled like in #decrypt.
+        def decryption_fiber(key, source)
+          Fiber.new do
+            data = ''.b
+            while data.length < BLOCK_SIZE && source.alive? && (new_data = source.resume)
+              data << new_data
+            end
+
+            algorithm = new(key, data.slice!(0, BLOCK_SIZE), :decrypt)
+
+            while source.alive? && (new_data = source.resume)
+              data << new_data
+              next if data.length < 2 * BLOCK_SIZE
+              new_data = data.slice!(0, data.length - BLOCK_SIZE - data.length % BLOCK_SIZE)
+              Fiber.yield(algorithm.process(new_data))
+            end
+
+            if data.length < BLOCK_SIZE || data.length % BLOCK_SIZE != 0
+              raise HexaPDF::EncryptionError, "Invalid data for decryption, need 32 + 16*n bytes"
+            end
+
+            unpad(algorithm.process(data))
+          end
+        end
+
+        # Returns a string of n random bytes.
+        #
+        # The specific AES algorithm class can override this class method to provide another
+        # method for generating random bytes.
+        def random_bytes(n)
+          SecureRandom.random_bytes(n)
+        end
+
+        private
+
+        # Pads the data to a muliple of BLOCK_SIZE using the PKCS#5 padding scheme and returns the
+        # result.
+        #
+        # See: PDF1.7 s7.6.2
+        def pad(data)
+          padding_length = BLOCK_SIZE - data.size % BLOCK_SIZE
+          data + padding_length.chr * padding_length
+        end
+
+        # Removes the padding from the data according to the PKCS#5 padding scheme and returns the
+        # result.
+        #
+        # See: PDF1.7 s7.6.2
+        def unpad(data)
+          padding_length = data.getbyte(-1)
+          if padding_length > BLOCK_SIZE || padding_length == 0
+            raise HexaPDF::EncryptionError, "Invalid AES padding length #{padding_length}"
+          end
+          data[0...-padding_length]
+        end
+
+      end
+
+      # Automatically extends the klass with the necessary class level methods.
+      def self.prepended(klass) # :nodoc:
+        klass.extend(ClassMethods)
+      end
+
+      # Creates a new AES object using the given encryption key and initialization vector.
+      #
+      # The mode must either be :encrypt or :decrypt.
+      #
+      # Classes prepending this module have to have their own initialization method as this method
+      # just performs basic checks.
+      def initialize(key, iv, mode)
+        unless VALID_KEY_LENGTH.include?(key.length)
+          raise HexaPDF::EncryptionError, "AES key length must be 128, 192 or 256 bit"
+        end
+        unless iv.length == BLOCK_SIZE
+          raise HexaPDF::EncryptionError, "AES initialization vector length must be 128 bit"
+        end
+        mode = mode.intern
+        super
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/encryption/arc4.rb

@@ -0,0 +1,93 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+module HexaPDF
+  module Encryption
+
+    # Common interface for ARC4 algorithms
+    #
+    # This module defines the common interface that is used by the security handlers to encrypt or
+    # decrypt data with ARC4. It has to be *prepended* by any ARC4 algorithm class.
+    #
+    # See the ClassMethods module for available class level methods of ARC4 algorithms.
+    #
+    # == Implementing an ARC4 Class
+    #
+    # An ARC4 class needs to define at least the following methods:
+    #
+    # initialize(key)::
+    #   Initializes the ARC4 algorithm with the given key.
+    #
+    # process(data)::
+    #   Processes the data and returns the encrypted/decrypted data. Since the ARC4 algorithm is
+    #   symmetric in regards to its inner workings, the same method can be used for encryption and
+    #   decryption.
+    module ARC4
+
+      # Convenience methods for decryption and encryption that operate according to the PDF
+      # specification.
+      #
+      # These methods will be available on the class object that prepends the ARC4 module.
+      module ClassMethods
+
+        # Encrypts the given +data+ with the +key+.
+        #
+        # See: PDF1.7 s7.6.2.
+        def encrypt(key, data)
+          new(key).process(data)
+        end
+        alias :decrypt :encrypt
+
+        # Returns a Fiber object that encrypts the data from the given source fiber with the
+        # +key+.
+        def encryption_fiber(key, source)
+          Fiber.new do
+            algorithm = new(key)
+            while source.alive? && (data = source.resume)
+              Fiber.yield(algorithm.process(data)) unless data.empty?
+            end
+          end
+        end
+        alias :decryption_fiber :encryption_fiber
+
+      end
+
+      # Automatically extends the klass with the necessary class level methods.
+      def self.prepended(klass) # :nodoc:
+        klass.extend(ClassMethods)
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/encryption/fast_aes.rb

@@ -0,0 +1,79 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'openssl'
+require 'hexapdf/error'
+require 'hexapdf/encryption/aes'
+
+module HexaPDF
+  module Encryption
+
+    # Implementation of the general encryption algorithm AES using OpenSSL as backend.
+    #
+    # Since OpenSSL is a native Ruby extension (that comes bundled with Ruby) it is much faster
+    # than the pure Ruby version and it can use the AES-NI instruction set on CPUs when available.
+    #
+    # This implementation is using AES in Cipher Block Chaining (CBC) mode.
+    #
+    # See: PDF1.7 s7.6.2
+    class FastAES
+
+      prepend AES
+
+      # Uses OpenSSL to generate the requested random bytes.
+      #
+      # See AES::ClassMethods#random_bytes for more information.
+      def self.random_bytes(n)
+        OpenSSL::Random.random_bytes(n)
+      end
+
+      # Creates a new FastAES object using the given encryption key and initialization vector.
+      #
+      # The mode must either be :encrypt or :decrypt.
+      def initialize(key, iv, mode)
+        @cipher = OpenSSL::Cipher.new("AES-#{key.length << 3}-CBC")
+        @cipher.send(mode)
+        @cipher.key = key
+        @cipher.iv = iv
+        @cipher.padding = 0
+      end
+
+      # Encrypts or decrypts the given data whose length must be a multiple of 16.
+      def process(data)
+        @cipher.update(data)
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/encryption/fast_arc4.rb

@@ -0,0 +1,67 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#++
+
+require 'openssl'
+require 'hexapdf/encryption/arc4'
+
+module HexaPDF
+  module Encryption
+
+    # Implementation of the general encryption algorithm ARC4 using OpenSSL as backend.
+    #
+    # See: PDF1.7 s7.6.2
+    class FastARC4
+
+      prepend ARC4
+
+      # Creates a new FastARC4 object using the given encryption key.
+      def initialize(key)
+        @cipher = OpenSSL::Cipher::RC4.new
+        @cipher.key_len = key.length
+        @cipher.key = key
+      end
+
+      # Processes the given data.
+      #
+      # Since this is a symmetric algorithm, the same method can be used for encryption and
+      # decryption.
+      def process(data)
+        @cipher.update(data)
+      end
+      alias :decrypt :process
+      alias :encrypt :process
+
+    end
+
+  end
+end