hexapdf 0.32.2 → 0.33.0

data/lib/hexapdf/dictionary_fields.rb

@@ -50,7 +50,12 @@ module HexaPDF
   # field object is automatically assigned a stateless converter object that knows if data read
   # from a PDF file potentially needs to be converted into a standard format before use.
   #
-  # The methods that need to be implemented by such stateless converter objects are:
+  # The available converter objects can be retrieved or modified via the Field.converters method.
+  #
+  #
+  # == Converter Objects
+  #
+  # The methods that need to be implemented by a stateless converter objects are the following:
   #
   # usable_for?(type)::
   #   Should return +true+ if the converter is usable for the given type.
@@ -63,19 +68,28 @@ module HexaPDF
   #   Should return the +converted+ data if conversion is possible and +nil+ otherwise. The +type+
   #   argument is the result of the Field#type method call and +document+ is the HexaPDF::Document
   #   for which the data should be converted.
+  #
+  # Since a converter usually doesn't need to store any data, it can be implemented as a module
+  # using class methods. This is how it is done for the built-in converter objects.
   module DictionaryFields
 
     # This constant should *always* be used for boolean fields.
+    #
+    # See: PDF2.0 s7.3.2
     Boolean = [TrueClass, FalseClass].freeze
 
     # PDFByteString is used for defining fields with strings in binary encoding.
+    #
+    # See: PDF2.0 s7.9.2.4
     PDFByteString = Class.new { private_class_method :new }
 
     # PDFDate is used for defining fields which store a date object as a string.
+    #
+    # See: PDF2.0 s7.9.4
     PDFDate = Class.new { private_class_method :new }
 
-    # A dictionary field contains information about one field of a structured PDF object and this
-    # information comes directly from the PDF specification.
+    # A field contains information about one field of a structured PDF object and this information
+    # comes directly from the PDF specification.
     #
     # By incorporating this field information into HexaPDF it is possible to do many things
     # automatically, like checking for the correct minimum PDF version to use or converting a date
@@ -91,9 +105,9 @@ module HexaPDF
 
       # Returns the converter for the given +type+ specification.
       #
-      # The converter list is checked for a suitable converter from the front to the back. So if
-      # two converters could potentially be used for the same type, the one that appears earlier
-      # is used.
+      # The converter list from #converters is checked for a suitable converter from the front to
+      # the back. So if two converters could potentially be used for the same type, the one that
+      # appears earlier is used.
       def self.converter_for(type)
         @converters.find {|converter| converter.usable_for?(type) }
       end
@@ -148,8 +162,7 @@ module HexaPDF
         !@default.nil?
       end
 
-      # Returns a duplicated default value, automatically taking unduplicatable classes into
-      # account.
+      # Returns a duplicated default value.
       def default
         @default.dup
       end
@@ -171,8 +184,10 @@ module HexaPDF
 
     end
 
-    # Converter module for fields of type Dictionary and its subclasses. The first class in the
-    # type array of the field is used for the conversion.
+    # Converter module for fields of type Dictionary and its subclasses.
+    #
+    # The first class in the type array of the field is used for the conversion. Symbol names for
+    # classes may also be used since they are automatically resolved.
     module DictionaryConverter
 
       # This converter is used when either a Symbol is provided as +type+ (for lazy loading) or
@@ -199,6 +214,8 @@ module HexaPDF
     end
 
     # Converter module for fields of type PDFArray.
+    #
+    # This converter ensures that arrays are wrapped by the PDFArray class for more convenient use.
     module ArrayConverter
 
       # This converter is usable if the +type+ is PDFArray.
@@ -220,6 +237,8 @@ module HexaPDF
     end
 
     # Converter module for string fields to automatically convert a string into UTF-8 encoding.
+    #
+    # See: PDF2.0 s7.9.2
     module StringConverter
 
       # This converter is usable if the +type+ is the String class.
@@ -231,8 +250,8 @@ module HexaPDF
       def self.additional_types
       end
 
-      # Converts the string into UTF-8 encoding, assuming it is a binary string. Otherwise +nil+ is
-      # returned.
+      # Converts the string into UTF-8 encoding, assuming it is a binary string (i.e. one not yet
+      # converted). Otherwise returns +nil+.
       def self.convert(str, _type, document)
         return unless str.kind_of?(String) && str.encoding == Encoding::BINARY
 
@@ -252,6 +271,8 @@ module HexaPDF
 
     # Converter module for binary string fields to automatically convert a string into binary
     # encoding.
+    #
+    # See: PDF2.0 s7.9.2.4
     module PDFByteStringConverter
 
       # This converter is usable if the +type+ is PDFByteString.
@@ -279,7 +300,7 @@ module HexaPDF
     # date format. When converting from a date string to a Time object, this is taken into
     # account.
     #
-    # See: PDF1.7 s7.9.4, ADB1.7 3.8.3
+    # See: PDF2.0 s7.9.4, ADB1.7 3.8.3
     module DateConverter
 
       # This converter is usable if the +type+ is PDFDate.
@@ -297,6 +318,8 @@ module HexaPDF
 
       # Checks if the given object is a string and converts into a Time object if possible.
       # Otherwise returns +nil+.
+      #
+      # This method takes some forms of mangled date strings into account that were found in the wild.
       def self.convert(str, _type, _document)
         return unless str.kind_of?(String) && (m = str.match(DATE_RE))
 
@@ -318,6 +341,8 @@ module HexaPDF
 
     # Converter module for file specification fields. A file specification in string format is
     # converted to the corresponding file specification dictionary.
+    #
+    # See: PDF2.0 s7.11, HexaPDF::Type::FileSpecification
     module FileSpecificationConverter
 
       # This converter is only used for the :Filespec type.
@@ -343,6 +368,8 @@ module HexaPDF
     end
 
     # Converter module for fields of type Rectangle.
+    #
+    # See: PDF2.0 s7.9.5
     module RectangleConverter
 
       # This converter is usable if the +type+ is Rectangle.
@@ -355,7 +382,8 @@ module HexaPDF
         Array
       end
 
-      # Wraps a given array in the Rectangle class. Otherwise returns +nil+.
+      # Wraps a given array using the Rectangle class or as a Null value if the array is invalid.
+      # Otherwise returns +nil+.
       def self.convert(data, _type, document)
         return unless data.kind_of?(Array) || data.kind_of?(HexaPDF::PDFArray)
         data.empty? ? document.wrap(nil) : document.wrap(data, type: Rectangle)

data/lib/hexapdf/digital_signature/cms_handler.rb

@@ -41,9 +41,9 @@ module HexaPDF
   module DigitalSignature
 
     # The signature handler for PKCS#7 a.k.a. CMS signatures. Those include, for example, the
-    # adbe.pkcs7.detached sub-filter.
+    # adbe.pkcs7.detached and ETSI.CAdES.detached sub-filters.
     #
-    # See: PDF1.7/2.0 s12.8.3.3
+    # See: PDF2.0 s12.8.3.3
     class CMSHandler < Handler
 
       # Creates a new signature handler for the given signature dictionary.

data/lib/hexapdf/digital_signature/handler.rb

@@ -41,7 +41,7 @@ module HexaPDF
 
     # The base signature handler providing common functionality.
     #
-    # Specific signature handler need to override methods if necessary and implement the needed
+    # Specific signature handlers need to override methods if necessary and implement the needed
     # ones that don't have a default implementation.
     class Handler
 

data/lib/hexapdf/digital_signature/pkcs1_handler.rb

@@ -43,10 +43,9 @@ module HexaPDF
     # The signature handler for PKCS#1 based sub-filters, the only being the adbe.x509.rsa_sha1
     # sub-filter.
     #
-    # Since PKCS#1 signatures are deprecated with PDF 2.0, the handler only provides the
-    # implementation for reading and verifying signatures.
+    # Note that PKCS#1 signatures are deprecated with PDF 2.0.
     #
-    # See: PDF1.7/2.0 s12.8.3.2
+    # See: PDF2.0 s12.8.3.2
     class PKCS1Handler < Handler
 
       # Returns the certificate chain.

data/lib/hexapdf/digital_signature/signature.rb

@@ -50,10 +50,10 @@ module HexaPDF
     # differ from use-case to use-case. Therefore HexaPDF provides as much diagnostic information as
     # possible so that the user can decide whether a signature is valid.
     #
-    # By defining a custom signature handler one is able to also customize the signature
-    # verification.
+    # By defining a custom signature handler based on BaseHandler or CMSHandler one is able to also
+    # customize the signature verification.
     #
-    # See: PDF1.7/2.0 s12.8.1, HexaPDF::Type::AcroForm::SignatureField
+    # See: PDF2.0 s12.8.1, HexaPDF::Type::AcroForm::SignatureField
     class Signature < Dictionary
 
       # Represents a transform parameters dictionary.
@@ -61,7 +61,7 @@ module HexaPDF
       # The allowed fields depend on the transform method, so not all fields are available all the
       # time.
       #
-      # See: PDF1.7 s12.8.2.2, s12.8.2.3, s12.8.2.4
+      # See: PDF2.0 s12.8.2.2, s12.8.2.3, s12.8.2.4
       class TransformParams < Dictionary
 
         define_type :TransformParams
@@ -117,7 +117,7 @@ module HexaPDF
 
       # Represents a signature reference dictionary.
       #
-      # See: PDF1.7/2.0 s12.8.1, HexaPDF::DigitalSignature::Signature
+      # See: PDF2.0 s12.8.1, HexaPDF::DigitalSignature::Signature
       class SignatureReference < Dictionary
 
         define_type :SigRef
@@ -202,7 +202,7 @@ module HexaPDF
         self[:Contents]
       end
 
-      # Returns the signed data as indicated by the /ByteRange entry as byte string.
+      # Returns the signed data as indicated by the /ByteRange entry as binary string.
       def signed_data
         unless document.revisions.parser
           raise HexaPDF::Error, "Can't load signed data without existing PDF file"

data/lib/hexapdf/digital_signature/signatures.rb

@@ -42,7 +42,7 @@ require 'hexapdf/error'
 module HexaPDF
   module DigitalSignature
 
-    # This class provides methods for interacting with digital signatures of a PDF file. Use it
+    # This class provides methods for interacting with digital signatures of a PDF file. It is used
     # through HexaPDF::Document#signatures.
     class Signatures
 
@@ -56,7 +56,7 @@ module HexaPDF
       # Creates a signing handler with the given attributes and returns it.
       #
       # A signing handler name is mapped to a class via the 'signature.signing_handler'
-      # configuration option. The default signing handler is DefaultHandler.
+      # configuration option. The default signing handler is Signing::DefaultHandler.
       def signing_handler(name: :default, **attributes)
         handler = @document.config.constantize('signature.signing_handler', name) do
           raise HexaPDF::Error, "No signing handler named '#{name}' is available"
@@ -90,19 +90,12 @@ module HexaPDF
       #
       # +handler+::
       #     The signing handler that provides the necessary methods for signing and adjusting the
-      #     signature and signature field objects to one's liking, see #handler and DefaultHandler.
+      #     signature and signature field objects to one's liking, see #signing_handler and
+      #     Signing::DefaultHandler.
       #
       # +write_options+::
       #     The key-value pairs of this hash will be passed on to the HexaPDF::Document#write
       #     method. Note that +incremental+ will be automatically set to ensure proper behaviour.
-      #
-      # The used signature object will have the following default values set:
-      #
-      # /Filter::    /Adobe.PPKLite
-      # /SubFilter:: /adbe.pkcs7.detached
-      # /M::         The current time.
-      #
-      # These values can be overridden in the #finalize_objects method of the signature handler.
       def add(file_or_io, handler, signature: nil, write_options: {})
         if signature && signature.type != :Sig
           signature_field = signature
@@ -123,6 +116,14 @@ module HexaPDF
           signature_field.create_widget(@document.pages[0], Rect: [0, 0, 0, 0])
         end
 
+        # Work-around for Adobe Acrobat to recognize images (https://stackoverflow.com/a/73011571/8203541)
+        signature_field.each_widget do |widget|
+          next unless (resources = widget.appearance&.resources)
+          resources[:XObject]&.each do |_name, entry|
+            entry[:Resources] ||= {}
+          end
+        end
+
         # Prepare signature object
         handler.finalize_objects(signature_field, signature)
         signature[:ByteRange] = [0, 1_000_000_000_000, 1_000_000_000_000, 1_000_000_000_000]
@@ -178,7 +179,7 @@ module HexaPDF
       #   signatures.each {|signature| block }   -> signatures
       #   signatures.each                        -> Enumerator
       #
-      # Iterates over all signatures in the order they are found.
+      # Iterates over all signatures in the order they are found in the PDF.
       def each
         return to_enum(__method__) unless block_given?
 

data/lib/hexapdf/digital_signature/signing/default_handler.rb

@@ -158,12 +158,18 @@ module HexaPDF
         #
         # If the certificate is provided, HexaPDF creates the signature object. Otherwise the
         # #external_signing callable object has to create it.
+        #
+        # See the class documentation section "Signing Modes" on how #certificate, #key and
+        # #external_signing play together.
         attr_accessor :certificate
 
         # The private key for the #certificate.
         #
         # If the key is provided, HexaPDF does the signing. Otherwise the #external_signing callable
         # object has to sign the data.
+        #
+        # See the class documentation section "Signing Modes" on how #certificate, #key and
+        # #external_signing play together.
         attr_accessor :key
 
         # The certificate chain that should be embedded in the PDF; usually contains all
@@ -191,21 +197,24 @@ module HexaPDF
         # * If #certificate is set and #key is not, it is just used for signing. Here it needs to
         #   accept the used digest algorithm and the already digested data as arguments and return
         #   the signature.
+        #
+        # Also dee the class documentation section "Signing Modes" on how #certificate, #key and
+        # #external_signing play together.
         attr_accessor :external_signing
 
-        # The reason for signing. If used, will be set on the signature object.
+        # The reason for signing. If used, will be set on the signature dictionary.
         attr_accessor :reason
 
-        # The signing location. If used, will be set on the signature object.
+        # The signing location. If used, will be set on the signature dictionary.
         attr_accessor :location
 
-        # The contact information. If used, will be set on the signature object.
+        # The contact information. If used, will be set on the signature dictionary.
         attr_accessor :contact_info
 
         # The size of the serialized signature that should be reserved.
         #
-        # If this attribute has not been set, an empty string will be signed using #sign to
-        # determine the signature size.
+        # If this attribute is not set, an empty string will be signed using #sign to determine the
+        # signature size.
         #
         # The size needs to be at least as big as the final signature, otherwise signing results in
         # an error.

data/lib/hexapdf/digital_signature/signing/signed_data_creator.rb

@@ -55,7 +55,7 @@ module HexaPDF
       #
       # Additionally, only RSA signatures are currently supported!
       #
-      # See: PDF1.7/2.0 s12.8.3.3, PDF2.0 s12.8.3.4, RFC5652, ETSI TS 102 778 Parts 1-4
+      # See: PDF2.0 s12.8.3.3, PDF2.0 s12.8.3.4, RFC5652, ETSI TS 102 778 Parts 1-4
       class SignedDataCreator
 
         # Creates a SignedDataCreator, sets the given attributes if they are not nil and then calls
@@ -88,8 +88,6 @@ module HexaPDF
         attr_accessor :timestamp_handler
 
         # Creates a new SignedData object.
-        #
-        # Use the attribute accessor methods to set the required attributes.
         def initialize
           @certificate = nil
           @key = nil
@@ -170,7 +168,7 @@ module HexaPDF
 
         # Digests the data and then signs it using the assigned key, or if the key is not available,
         # by yielding to the caller.
-        def digest_and_sign_data(data)
+        def digest_and_sign_data(data) #:yields: digest_algorithm, hashed_data
           hash = OpenSSL::Digest.digest(@digest_algorithm, data)
           if @key
             @key.sign_raw(@digest_algorithm, hash)

data/lib/hexapdf/digital_signature/signing/timestamp_handler.rb

@@ -75,19 +75,19 @@ module HexaPDF
         # The size of the serialized signature that should be reserved.
         #
         # If this attribute has not been set, an empty string will be signed using #sign to
-        # determine the signature size which will contact the TSA server
+        # determine the signature size. Note thtat this will contact the TSA server!
         #
         # The size needs to be at least as big as the final signature, otherwise signing results in
         # an error.
         attr_writer :signature_size
 
-        # The reason for timestamping. If used, will be set on the signature object.
+        # The reason for timestamping. If used, will be set on the signature dictionary.
         attr_accessor :reason
 
-        # The timestamping location. If used, will be set on the signature object.
+        # The timestamping location. If used, will be set on the signature dictionary.
         attr_accessor :location
 
-        # The contact information. If used, will be set on the signature object.
+        # The contact information. If used, will be set on the signature dictionary.
         attr_accessor :contact_info
 
         # Creates a new TimestampHandler with the given attributes.

data/lib/hexapdf/digital_signature/signing.rb

@@ -41,6 +41,10 @@ module HexaPDF
 
     # This module contains everything related to the signing of a PDF document, i.e. signing
     # handlers and the actual code for signing.
+    #
+    # * The DefaultHandler is the standard signing handler and should be sufficient for most cases.
+    # * The TimestampHandler is used for timestamping purposes.
+    # * The SignedDataCreator provides the functionality to create custom CMS signed data objects.
     module Signing
 
       autoload(:DefaultHandler, 'hexapdf/digital_signature/signing/default_handler')

data/lib/hexapdf/digital_signature/verification_result.rb

@@ -37,7 +37,7 @@
 module HexaPDF
   module DigitalSignature
 
-    # Holds the result information when verifying a signature.
+    # Holds the result of verifying a signature.
     class VerificationResult
 
       # :nodoc:
@@ -47,7 +47,7 @@ module HexaPDF
         error: {info: -1, warning: -1, error: 0},
       }
 
-      # This structure represents a single status message, containing the type (:info, :warning,
+      # This structure represents a single status message, containing the type (:info, :warning, or
       # :error) and the content of the message.
       Message = Struct.new(:type, :content) do
         def <=>(other)

data/lib/hexapdf/digital_signature.rb

@@ -39,9 +39,14 @@ module HexaPDF
   # PDF documents can be signed using digital signatures. Such a signature can be used to
   # authenticate the identity of the signer and the contents of the documents.
   #
-  # This module contains all code related to digital signatures in PDF.
+  # This module contains all code related to digital signatures in PDF:
   #
-  # See: PDF1.7/2.0 s12.8
+  # * Signatures provides the convenience interface accessible via Document#signatures.
+  # * Signature implements the PDF signature dictionary.
+  # * BaseHandler, CMSHandler and PKCS1Handler are used for verifying existing signatures.
+  # * The Signing module implements the functionality for creating digital signatures.
+  #
+  # See: PDF2.0 s12.8
   module DigitalSignature
 
     autoload(:Signatures, 'hexapdf/digital_signature/signatures')

data/lib/hexapdf/document/destinations.rb

@@ -49,7 +49,7 @@ module HexaPDF
     # may be named and later referenced through the name. This class allows to create destinations
     # with or without a name.
     #
-    # See: PDF1.7 s12.3.2
+    # See: PDF2.0 s12.3.2
     class Destinations
 
       # Wraps an explicit destination array to allow easy access to query its properties.
@@ -127,8 +127,9 @@ module HexaPDF
             destination[2..-1].all? {|item| item.nil? || item.kind_of?(Numeric) }
         end
 
-        # Creates a new Destination for the given +destination+ which may be an explicit destination
-        # array or a dictionary with a /D entry (as allowed for a named destination).
+        # Creates a new Destination for the given +destination+ specification which may be an
+        # explicit destination array or a dictionary with a /D entry (as allowed for a named
+        # destination).
         def initialize(destination)
           @destination = if destination.kind_of?(HexaPDF::Dictionary) || destination.kind_of?(Hash)
                            destination[:D]
@@ -235,15 +236,15 @@ module HexaPDF
       #   destinations.use_or_create(type:, page, **options)           -> destination
       #
       # Uses the given destination name/array or creates a destination array based on the given
-      # +value+.
+      # arguments.
       #
       # This is the main utility method for other parts of HexaPDF for getting a valid destination
-      # array based on various different types of the given +value+:
+      # array based on various different types of the given arguments:
       #
       # String::
       #
       #     If a string is provided, it is assumed to be a named destination. If the named
-      #     destination exists, the value itself is returned. Otherwise an error is raised.
+      #     destination exists, the destination itself is returned. Otherwise an error is raised.
       #
       # Array::
       #
@@ -438,7 +439,7 @@ module HexaPDF
       # :call-seq:
       #   destinations.add(name, destination)
       #
-      # Adds the given +destination+ under +name+ to the destinations name tree.
+      # Adds the given +destination+ under +name+ (a String) to the destinations name tree.
       #
       # If the name does already exist, an error is raised.
       def add(name, destination)
@@ -448,8 +449,8 @@ module HexaPDF
       # :call-seq:
       #   destinations.delete(name)    -> destination
       #
-      # Deletes the given destination from the destinations name tree and returns it or +nil+ if no
-      # destination was registered under that name.
+      # Deletes the destination specified via +name+ (a String) from the destinations name tree and
+      # returns it or +nil+ if no destination was registered under that name.
       def delete(name)
         destinations.delete_entry(name)
       end
@@ -487,8 +488,8 @@ module HexaPDF
       # :call-seq:
       #   destinations[name]    -> destination
       #
-      # Returns the destination registered under the given +name+ or +nil+ if no destination was
-      # registered under that name.
+      # Returns the destination registered under the given +name+ (a String) or +nil+ if no
+      # destination was registered under that name.
       def [](name)
         destinations.find_entry(name)
       end

data/lib/hexapdf/document/files.rb

@@ -96,7 +96,7 @@ module HexaPDF
       #
       # Iterates over indirect file specification dictionaries of the PDF.
       #
-      # By default, only the file specifications in their standard locations, namely in the
+      # By default, only the file specifications in their standard locations, i.e. 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 can
       # be much slower.

data/lib/hexapdf/document/fonts.rb

@@ -53,7 +53,7 @@ module HexaPDF
       # :call-seq:
       #   fonts.add(name, **options)            -> font
       #
-      # Adds the font to the document and returns it (using the loaders specified with the
+      # Adds the font to the document and returns it (using the font loaders specified with the
       # configuration option 'font_loaders').
       #
       # If a font with the same parameters has been loaded before, the cached font object is used.