hexapdf 0.19.0 → 0.20.0

data/lib/hexapdf/content/graphics_state.rb

@@ -512,7 +512,7 @@ module HexaPDF
       attr_accessor :leading
 
       # The font for the text.
-      attr_accessor :font
+      attr_reader :font
 
       # The font size.
       attr_reader :font_size
@@ -552,9 +552,11 @@ module HexaPDF
 
       # The scaled font size used in glyph displacement calculations.
       #
-      # This returns the font size divided by 1000 multiplied by #scaled_horizontal_scaling.
+      # This returns the font size multiplied by the scaling factor from glyph space to text space
+      # (0.001 for all fonts except Type3 fonts or the scaling specified in /FontMatrix for Type3
+      # fonts) and multiplied by #scaled_horizontal_scaling.
       #
-      # See PDF1.7 s9.4.4
+      # See PDF1.7 s9.4.4, HexaPDF::Type::FontType3
       attr_reader :scaled_font_size
 
       # The scaled horizontal scaling used in glyph displacement calculations.
@@ -665,6 +667,15 @@ module HexaPDF
         self.fill_color = color_space.default_color
       end
 
+      ##
+      # :attr_writer: font
+      #
+      # Sets the font and updates the glyph space to text space scaling.
+      def font=(font)
+        @font = font
+        update_scaled_font_size
+      end
+
       ##
       # :attr_writer: character_spacing
       #
@@ -689,7 +700,7 @@ module HexaPDF
       # Sets the font size and updates the scaled font size.
       def font_size=(size)
         @font_size = size
-        @scaled_font_size = size / 1000.0 * @scaled_horizontal_scaling
+        update_scaled_font_size
       end
 
       ##
@@ -702,7 +713,15 @@ module HexaPDF
         @scaled_horizontal_scaling = scaling / 100.0
         @scaled_character_spacing = @character_spacing * @scaled_horizontal_scaling
         @scaled_word_spacing = @word_spacing * @scaled_horizontal_scaling
-        @scaled_font_size = @font_size / 1000.0 * @scaled_horizontal_scaling
+        update_scaled_font_size
+      end
+
+      private
+
+      # Updates the cached value for the scaled font size.
+      def update_scaled_font_size
+        @scaled_font_size = @font_size * (@font&.glyph_scaling_factor || 0.001) *
+          @scaled_horizontal_scaling
       end
 
     end

data/lib/hexapdf/content/processor.rb

@@ -455,7 +455,7 @@ module HexaPDF
       # Decodes the given array containing text and positioning information while assuming that the
       # writing direction is vertical.
       def decode_vertical_text(_data)
-        raise NotImplementedError
+        raise "Not yet implemented"
       end
 
     end

data/lib/hexapdf/document/signatures.rb

@@ -0,0 +1,327 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2021 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.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'openssl'
+require 'hexapdf/error'
+
+module HexaPDF
+  class Document
+
+    # This class provides methods for interacting with digital signatures of a PDF file.
+    class Signatures
+
+      # This is the default signing handler which provides the ability to sign a document with a
+      # provided certificate using the adb.pkcs7.detached algorithm.
+      #
+      # Additional functionality:
+      #
+      # * Optionally setting the reason, location and contact information.
+      # * Making the signature a certification signature by applying the DocMDP transform method.
+      #
+      # == Implementing a Signing Handler
+      #
+      # This class also serves as an example on how to create a custom handler: The public methods
+      # #filter_name, #sub_filter_name, #signature_size, #finalize_objects and #sign are used by the
+      # digital signature algorithm.
+      #
+      # Once a custom signing handler has been created, it can be registered under the
+      # 'signature.signing_handler' configuration option for easy use. It has to take keyword
+      # arguments in its initialize method to be compatible with the Signatures#handler method.
+      class DefaultHandler
+
+        # The certificate with which to sign the PDF.
+        attr_accessor :certificate
+
+        # The private key for the #certificate.
+        attr_accessor :key
+
+        # The certificate chain that should be embedded in the PDF; normally contains all
+        # certificates up to the root certificate.
+        attr_accessor :certificate_chain
+
+        # The reason for signing. If used, will be set on the signature object.
+        attr_accessor :reason
+
+        # The signing location. If used, will be set on the signature object.
+        attr_accessor :location
+
+        # The contact information. If used, will be set on the signature object.
+        attr_accessor :contact_info
+
+        # The DocMDP permissions that should be set on the document.
+        #
+        # See #doc_mdp_permissions=
+        attr_reader :doc_mdp_permissions
+
+        # Creates a new DefaultHandler with the given attributes.
+        def initialize(**arguments)
+          arguments.each {|name, value| send("#{name}=", value) }
+        end
+
+        # Returns the name to be set on the /Filter key when using this signing handler.
+        def filter_name
+          :"Adobe.PPKLite"
+        end
+
+        # Returns the name to be set on the /SubFilter key when using this signing handler.
+        def sub_filter_name
+          :"adbe.pkcs7.detached"
+        end
+
+        # Sets the DocMDP permissions that should be applied to the document.
+        #
+        # Valid values for +permissions+ are:
+        #
+        # +nil+::
+        #     Don't set any DocMDP permissions (default).
+        #
+        # +:no_changes+ or 1::
+        #     No changes whatsoever are allowed.
+        #
+        # +:form_filling+ or 2::
+        #     Only filling in forms and signing are allowed.
+        #
+        # +:form_filling_and_annotations+ or 3::
+        #     Only filling in forms, signing and annotation creation/deletion/modification are
+        #     allowed.
+        def doc_mdp_permissions=(permissions)
+          case permissions
+          when :no_changes, 1 then @doc_mdp_permissions = 1
+          when :form_filling, 2 then @doc_mdp_permissions = 2
+          when :form_filling_and_annotations, 3 then @doc_mdp_permissions = 3
+          when nil then @doc_mdp_permissions = nil
+          else
+            raise ArgumentError, "Invalid permissions value '#{permissions.inspect}'"
+          end
+        end
+
+        # Returns the size of the signature that would be created.
+        def signature_size
+          sign("").size
+        end
+
+        # Finalizes the signature field as well as the signature dictionary before writing.
+        def finalize_objects(_signature_field, signature)
+          signature[:Reason] = reason if reason
+          signature[:Location] = location if location
+          signature[:ContactInfo] = contact_info if contact_info
+
+          if doc_mdp_permissions
+            doc = signature.document
+            if doc.signatures.count > 1
+              raise HexaPDF::Error, "Can set DocMDP access permissions only on first signature"
+            end
+            params = doc.add({Type: :TransformParams, V: :'1.2', P: doc_mdp_permissions})
+            sigref = doc.add({Type: :SigRef, TransformMethod: :DocMDP, DigestMethod: :SHA1,
+                              TransformParams: params})
+            signature[:Reference] = [sigref]
+            (doc.catalog[:Perms] ||= {})[:DocMDP] = signature
+          end
+        end
+
+        # Returns the DER serialized OpenSSL::PKCS7 structure containing the signature for the given
+        # data.
+        def sign(data)
+          OpenSSL::PKCS7.sign(@certificate, @key, data, @certificate_chain,
+                              OpenSSL::PKCS7::DETACHED | OpenSSL::PKCS7::BINARY).to_der
+        end
+
+      end
+
+      include Enumerable
+
+      # Creates a new Signatures object for the given PDF document.
+      def initialize(document)
+        @document = document
+      end
+
+      # Creates a signing handler with the given options and returns it.
+      #
+      # A signing handler name is mapped to a class via the 'signature.signing_handler'
+      # configuration option.
+      def handler(name: :default, **options)
+        handler = @document.config.constantize('signature.signing_handler', name) do
+          raise HexaPDF::Error, "No signing handler named '#{name}' is available"
+        end
+        handler.new(**options)
+      end
+
+      # Adds a signature to the document and returns the corresponding signature object.
+      #
+      # This method will add a new signature to the document and write the updated document to the
+      # given file or IO stream. Afterwards the document can't be modified anymore and still retain
+      # a correct digital signature; create a new document based on the file or IO stream instead.
+      #
+      # +signature+::
+      #     Can either be a signature object (determined via the /Type key), a signature field or
+      #     +nil+. Providing a signature object or signature field provides for more control, e.g.:
+      #
+      #     * Setting values for optional signature object fields like /Reason and /Location.
+      #     * (In)directly specifying which signature field should be used.
+      #
+      #     If a signature object is provided and it is not associated with an AcroForm signature
+      #     field, a new signature field is created and added to the main AcroForm object, creating
+      #     that if necessary.
+      #
+      #     If a signature field is provided and it already has a signature object as field value,
+      #     that signature object is discarded.
+      #
+      #     If the signature field doesn't have a widget, a non-visible one is created on the first
+      #     page.
+      #
+      # +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.
+      #
+      # +write_options+::
+      #     The key-value pairs of this hash will be passed on to the HexaPDF::Document#write
+      #     command. Note that +incremental+ will be automatically set if signing an already
+      #     existing file.
+      def add(file_or_io, handler, signature: nil, write_options: {})
+        if signature && signature.type != :Sig
+          signature_field = signature
+          signature = signature_field.field_value
+        end
+        signature ||= @document.add({Type: :Sig})
+
+        # Prepare AcroForm
+        form = @document.acro_form(create: true)
+        form.signature_flag(:signatures_exist, :append_only)
+
+        # Prepare signature field
+        signature_field ||= form.each_field.find {|field| field.field_value == signature } ||
+          form.create_signature_field(generate_field_name)
+        signature_field.field_value = signature
+
+        if signature_field.each_widget.to_a.empty?
+          signature_field.create_widget(@document.pages[0], Rect: [0, 0, 0, 0])
+        end
+
+        # Prepare signature object
+        signature[:Filter] = handler.filter_name
+        signature[:SubFilter] = handler.sub_filter_name
+        signature[:ByteRange] = [0, 1_000_000_000_000, 1_000_000_000_000, 1_000_000_000_000]
+        signature[:Contents] = '00' * handler.signature_size # twice the size due to hex encoding
+        signature[:M] = Time.now
+
+        io = if file_or_io.kind_of?(String)
+               File.open(file_or_io, 'w+')
+             else
+               file_or_io
+             end
+
+        # Save the current state so that we can determine the correct /ByteRange value and set the
+        # values
+        handler.finalize_objects(signature_field, signature)
+        section = @document.write(io, incremental: true, **write_options)
+        data = section.map {|oid, _gen, entry| [entry.pos, oid] if entry.in_use? }.compact.sort
+        index = data.index {|_pos, oid| oid == signature.oid }
+        signature_offset = data[index][0]
+        signature_length = data[index + 1][0] - data[index][0]
+        io.pos = signature_offset
+        signature_data = io.read(signature_length)
+
+        io.rewind
+        file_data = io.read
+
+        # Calculate the offsets for the /ByteRange
+        contents_offset = signature_offset + signature_data.index('Contents(') + 8
+        offset2 = contents_offset + signature[:Contents].size + 2 # +2 because of the needed < and >
+        length2 = file_data.size - offset2
+        signature[:ByteRange] = [0, contents_offset, offset2, length2]
+
+        # Set the correct /ByteRange value
+        signature_data.sub!(/ByteRange\[0 1000000000000 1000000000000 1000000000000\]/) do |match|
+          length = match.size
+          result = "ByteRange[0 #{contents_offset} #{offset2} #{length2}]"
+          result.ljust(length)
+        end
+
+        # Now everything besides the /Contents value is correct, so we can read the contents for
+        # signing
+        file_data[signature_offset, signature_length] = signature_data
+        signed_contents = file_data[0, contents_offset] << file_data[offset2, length2]
+        signature[:Contents] = handler.sign(signed_contents)
+
+        # Set the correct /Contents value as hexstring
+        signature_data.sub!(/Contents\(0+\)/) do |match|
+          length = match.size
+          result = "Contents<#{signature[:Contents].unpack1('H*')}"
+          "#{result.ljust(length - 1, '0')}>"
+        end
+
+        io.pos = signature_offset
+        io.write(signature_data)
+
+        signature
+      ensure
+        io.close if io && io != file_or_io
+      end
+
+      # :call-seq:
+      #   signatures.each {|signature| block }   -> signatures
+      #   signatures.each                        -> Enumerator
+      #
+      # Iterates over all signatures in the order they are found.
+      def each
+        return to_enum(__method__) unless block_given?
+
+        return [] unless (form = @document.acro_form)
+        form.each_field do |field|
+          yield(field.field_value) if field.field_type == :Sig && field.field_value
+        end
+      end
+
+      # Returns the number of signatures in the PDF document. May be zero if the document has no
+      # signatures.
+      def count
+        each.to_a.size
+      end
+
+      private
+
+      # Generates a field name for a signature field.
+      def generate_field_name
+        index = (@document.acro_form.each_field.
+                 map {|field| field.full_field_name.scan(/\ASignature(\d+)/).first&.first.to_i }.
+                 max || 0) + 1
+        "Signature#{index}"
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/document.rb

@@ -36,6 +36,7 @@
 
 require 'stringio'
 require 'hexapdf/error'
+require 'hexapdf/data_dir'
 require 'hexapdf/content'
 require 'hexapdf/configuration'
 require 'hexapdf/reference'
@@ -104,6 +105,7 @@ module HexaPDF
     autoload(:Fonts, 'hexapdf/document/fonts')
     autoload(:Images, 'hexapdf/document/images')
     autoload(:Files, 'hexapdf/document/files')
+    autoload(:Signatures, 'hexapdf/document/signatures')
 
     # :call-seq:
     #   Document.open(filename, **docargs)                   -> doc
@@ -617,6 +619,30 @@ module HexaPDF
       @security_handler
     end
 
+    # Returns +true+ if the document is signed, i.e. contains digital signatures.
+    def signed?
+      acro_form&.signature_flag?(:signatures_exist)
+    end
+
+    # Returns an array with the digital signatures of this document.
+    def signatures
+      @signatures ||= Signatures.new(self)
+    end
+
+    # Signs the document and writes it to the given file or IO object.
+    #
+    # For details on the arguments +file_or_io+, +signature+ and +write_options+ see
+    # HexaPDF::Document::Signatures#add.
+    #
+    # The signing handler to be used is determined by the +handler+ argument together with the rest
+    # of the keyword arguments (see HexaPDF::Document::Signatures#handler for details).
+    #
+    # If not changed, the default signing handler is HexaPDF::Document::Signatures::DefaultHandler.
+    def sign(file_or_io, handler: :default, signature: nil, write_options: {}, **handler_options)
+      handler = signatures.handler(name: handler, **handler_options)
+      signatures.add(file_or_io, handler, signature: signature, write_options: write_options)
+    end
+
     # Validates all objects, or, if +only_loaded+ is +true+, only loaded objects, with optional
     # auto-correction, and returns +true+ if everything is fine.
     #

data/lib/hexapdf/encryption/standard_security_handler.rb

@@ -328,8 +328,7 @@ module HexaPDF
           raise(HexaPDF::UnsupportedEncryptionError,
                 "Invalid /R value for standard security handler")
         elsif dict[:R] <= 4 && !document.trailer[:ID].kind_of?(PDFArray)
-          raise(HexaPDF::EncryptionError,
-                "Document ID for needed for decryption")
+          document.trailer[:ID] = ['', '']
         end
         @trailer_id_hash = trailer_id_hash
 

data/lib/hexapdf/importer.rb

@@ -93,7 +93,7 @@ module HexaPDF
       mapped_object = @mapper[object.data]&.__getobj__ if object.kind_of?(HexaPDF::Object)
       if object.kind_of?(HexaPDF::Object) && object.document? && @source != object.document
         raise HexaPDF::Error, "Import error: Incorrect document object for importer"
-      elsif mapped_object && mapped_object == @destination.object(mapped_object)
+      elsif mapped_object && !mapped_object.null?
         mapped_object
       else
         duplicate(object)

data/lib/hexapdf/layout/style.rb

@@ -1069,7 +1069,8 @@ module HexaPDF
 
       # The font size scaled appropriately.
       def scaled_font_size
-        @scaled_font_size ||= calculated_font_size / 1000.0 * scaled_horizontal_scaling
+        @scaled_font_size ||= calculated_font_size * font.pdf_object.glyph_scaling_factor *
+          scaled_horizontal_scaling
       end
 
       # The character spacing scaled appropriately.

data/lib/hexapdf/object.rb

@@ -333,10 +333,12 @@ module HexaPDF
       (oid == other.oid ? gen <=> other.gen : oid <=> other.oid)
     end
 
-    # Returns +true+ if the other object is an Object and wraps the same #data structure, or if the
-    # other object is a Reference with the same oid/gen.
+    # Returns +true+ if the other object is an Object and wraps the same #data structure, if the
+    # other object is a Reference with the same oid/gen, or if this object is not indirect and its
+    # value is equal to the other object.
     def ==(other)
-      (other.kind_of?(Object) && data == other.data) || (other.kind_of?(Reference) && other == self)
+      (other.kind_of?(Object) && data == other.data) || (other.kind_of?(Reference) && other == self) ||
+        (!indirect? && other == data.value)
     end
 
     # Returns +true+ if the other object references the same PDF object as this object.

data/lib/hexapdf/parser.rb

@@ -62,9 +62,15 @@ module HexaPDF
       @object_stream_data = {}
       @reconstructed_revision = nil
       @in_reconstruct_revision = false
+      @contains_xref_streams = false
       retrieve_pdf_header_offset_and_version
     end
 
+    # Returns +true+ if the PDF file contains cross-reference streams.
+    def contains_xref_streams?
+      @contains_xref_streams
+    end
+
     # Loads the indirect (potentially compressed) object specified by the given cross-reference
     # entry.
     #
@@ -230,6 +236,7 @@ module HexaPDF
           maybe_raise("Cross-reference stream doesn't contain entry for itself", pos: pos)
           xref_section.add_in_use_entry(obj.oid, obj.gen, pos)
         end
+        @contains_xref_streams = true
       end
       xref_section.delete(0)
       [xref_section, trailer]
@@ -335,7 +342,8 @@ module HexaPDF
       step_size = 1024
       pos = @io.pos
       eof_not_found = pos == 0
-      startxref_missing = false
+      startxref_missing = startxref_mangled = false
+      startxref_offset = nil
 
       while pos != 0
         @io.pos = [pos - step_size, 0].max
@@ -343,27 +351,31 @@ module HexaPDF
         lines = @io.read(step_size + 40).split(/[\r\n]+/)
 
         eof_index = lines.rindex {|l| l.strip == '%%EOF' }
-        unless eof_index
+        if !eof_index
           eof_not_found = true
-          next
-        end
-        unless eof_index >= 2 && lines[eof_index - 2].strip == "startxref"
+        elsif lines[eof_index - 1].strip =~ /\Astartxref\s(\d+)\z/
+          startxref_offset = $1.to_i
+          startxref_mangled = true
+          break # we found it even if it the syntax is not entirely correct
+        elsif eof_index < 2 || lines[eof_index - 2].strip != "startxref"
           startxref_missing = true
-          next
+        else
+          startxref_offset = lines[eof_index - 1].to_i
+          break # we found it
         end
-
-        break # we found the startxref offset
       end
 
       if eof_not_found
         maybe_raise("PDF file trailer with end-of-file marker not found", pos: pos,
                     force: !eof_index)
+      elsif startxref_mangled
+        maybe_raise("PDF file trailer keyword startxref on same line as value", pos: pos)
       elsif startxref_missing
         maybe_raise("PDF file trailer is missing startxref keyword", pos: pos,
                     force: eof_index < 2 || lines[eof_index - 2].strip != "startxref")
       end
 
-      @startxref_offset = lines[eof_index - 1].to_i
+      @startxref_offset = startxref_offset
     end
 
     # Returns the reconstructed revision.

data/lib/hexapdf/rectangle.rb

@@ -114,12 +114,6 @@ module HexaPDF
       self[3] = self[1] + val
     end
 
-    # Compares this rectangle to +other+ like in Object#== but also allows comparison to simple
-    # arrays if the rectangle is a direct object.
-    def ==(other)
-      super || (other.kind_of?(Array) && !indirect? && other == data.value)
-    end
-
     private
 
     # Ensures that the value is an array containing four numbers that specify the bottom left and

data/lib/hexapdf/revision.rb

@@ -190,7 +190,7 @@ module HexaPDF
       obj.data.value = nil
       obj.document = nil
       if mark_as_free
-        add_without_check(HexaPDF::Object.new(nil, oid: obj.oid, gen: obj.gen))
+        add_without_check(HexaPDF::Object.new(obj.data))
       else
         @xref_section.delete(ref_or_oid)
         @objects.delete(ref_or_oid)
@@ -228,7 +228,8 @@ module HexaPDF
     #   revision.each_modified_object {|obj| block }   -> revision
     #   revision.each_modified_object                  -> Enumerator
     #
-    # Calls the given block once for each object that has been modified since it was loaded.
+    # Calls the given block once for each object that has been modified since it was loaded. Deleted
+    # object and cross-reference streams are ignored.
     #
     # Note that this also means that for revisions without an associated cross-reference section all
     # loaded objects will be yielded.
@@ -238,12 +239,18 @@ module HexaPDF
       @objects.each do |oid, gen, obj|
         if @xref_section.entry?(oid, gen)
           stored_obj = @loader.call(@xref_section[oid, gen])
-          if obj.data.value != stored_obj.data.value || obj.data.stream != stored_obj.data.stream
-            yield(obj)
+          next if (stored_obj.type == :ObjStm || stored_obj.type == :XRef) && obj.null?
+
+          streams_are_same = (obj.data.stream == stored_obj.data.stream)
+          next if obj.value == stored_obj.value && streams_are_same
+
+          if obj.value.kind_of?(Hash) && stored_obj.value.kind_of?(Hash)
+            keys = obj.value.keys | stored_obj.value.keys
+            next if keys.all? {|key| obj[key] == stored_obj[key] } && streams_are_same
           end
-        else
-          yield(obj)
         end
+
+        yield(obj)
       end
 
       self

data/lib/hexapdf/type/acro_form/appearance_generator.rb

@@ -458,10 +458,8 @@ module HexaPDF
           option_items = @field.option_items
           top_index = @field.list_box_top_index
           items = [Layout::TextFragment.create(option_items[top_index..-1].join("\n"), style)]
-
-          indices = @field[:I] || []
-          value_indices = [@field.field_value].flatten.compact.map {|val| option_items.index(val) }
-          indices = value_indices if indices != value_indices
+          # Should use /I but if it differs from /V, we need to use /V; so just use /V...
+          indices = [@field.field_value].flatten.compact.map {|val| option_items.index(val) }
 
           layouter = Layout::TextLayouter.new(style)
           layouter.style.align(@field.text_alignment).line_spacing(:proportional, 1.25)

data/lib/hexapdf/type/acro_form/field.rb

@@ -310,6 +310,8 @@ module HexaPDF
             widget = document.wrap(self)
           end
 
+          widget.flag(:print)
+          widget[:P] = page
           (page[:Annots] ||= []) << widget
 
           widget

data/lib/hexapdf/type/acro_form/form.rb

@@ -75,7 +75,7 @@ module HexaPDF
 
         define_type :XXAcroForm
 
-        define_field :Fields,          type: PDFArray, required: true, version: '1.2'
+        define_field :Fields,          type: PDFArray, required: true, default: [], version: '1.2'
         define_field :NeedAppearances, type: Boolean, default: false
         define_field :SigFlags,        type: Integer, version: '1.3'
         define_field :CO,              type: PDFArray, version: '1.3'
@@ -323,6 +323,14 @@ module HexaPDF
           end
         end
 
+        # Creates a signature field with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        def create_signature_field(name)
+          create_field(name, :Sig) {}
+        end
+
         # Returns the dictionary containing the default resources for form field appearance streams.
         def default_resources
           self[:DR] ||= document.wrap({ProcSet: [:PDF, :Text, :ImageB, :ImageC, :ImageI]},