hexapdf 0.19.3 → 0.20.3

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/security_handler.rb

@@ -249,6 +249,10 @@ module HexaPDF
         @document = document
         @encrypt_dict_hash = nil
         @encryption_details = {}
+
+        @is_encrypt_dict = document.revisions.each.with_object({}) do |rev, hash|
+          hash[rev.trailer[:Encrypt]] = true
+        end
       end
 
       # Checks if the encryption key computed by this security handler is derived from the
@@ -262,7 +266,7 @@ module HexaPDF
       #
       # See: PDF1.7 s7.6.2
       def decrypt(obj)
-        return obj if obj == document.trailer[:Encrypt] || obj.type == :XRef
+        return obj if @is_encrypt_dict[obj] || obj.type == :XRef
 
         key = object_key(obj.oid, obj.gen, string_algorithm)
         each_string_in_object(obj.value) do |str|

data/lib/hexapdf/font/encoding/glyph_list.rb

@@ -131,13 +131,12 @@ module HexaPDF
         def load_file(file)
           name2uni = {}
           uni2name = {}
-          File.open(file, 'rb') do |f|
+          File.open(file, 'r:UTF-8') do |f|
+            25.times { f.gets } # Skip comments
             while (line = f.gets)
-              next if line.start_with?('#')
-              index = line.index(';')
-              name = line[0, index].to_sym
-              codes = line[index + 1, 50].split(" ").map(&:hex).pack('U*')
-              name2uni[name] = codes
+              name, codes = line.split(';', 2)
+              name = name.to_sym
+              name2uni[name] = codes.chomp!
               uni2name[codes] = name unless uni2name.key?(codes)
             end
           end

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/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/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/task/dereference.rb

@@ -68,9 +68,9 @@ module HexaPDF
 
       def execute #:nodoc:
         if @object
-          dereference(@object)
+          dereference_all(@object)
         else
-          dereference(@doc.trailer)
+          dereference_all(@doc.trailer)
           @result = []
           @doc.each(only_current: false) do |obj|
             if !@seen.key?(obj.data) && obj.type != :ObjStm && obj.type != :XRef
@@ -83,6 +83,11 @@ module HexaPDF
         end
       end
 
+      def dereference_all(object) # :nodoc:
+        @dereference_later = [object]
+        dereference(@dereference_later.pop) until @dereference_later.empty?
+      end
+
       def dereference(object) #:nodoc:
         return object if object.nil? || @seen.key?(object.data)
         @seen[object.data] = true
@@ -97,9 +102,12 @@ module HexaPDF
         when Array
           val.map! {|v| recurse(v) }
         when HexaPDF::Reference
-          dereference(@doc.object(val))
+          val = @doc.object(val)
+          @dereference_later.push(val)
+          val
         when HexaPDF::Object
-          dereference(val)
+          @dereference_later.push(val)
+          val
         else
           val
         end

data/lib/hexapdf/task/optimize.rb

@@ -234,7 +234,7 @@ module HexaPDF
           page.contents = processor.result
           page[:Contents].set_filter(:FlateDecode)
           xobjects = page.resources[:XObject]
-          processor.used_references.each {|ref| used_refs[xobjects[ref]] = true }
+          processor.used_references.each {|ref| used_refs[xobjects[ref]] = true } if xobjects
         end
         used_refs
       end
@@ -245,7 +245,7 @@ module HexaPDF
         unless used_refs
           used_refs = {}
           doc.pages.each do |page|
-            xobjects = page.resources[:XObject]
+            next unless (xobjects = page.resources[:XObject])
             HexaPDF::Content::Parser.parse(page.contents) do |op, operands|
               used_refs[xobjects[operands[0]]] = true if op == :Do
             end
@@ -253,7 +253,7 @@ module HexaPDF
         end
 
         doc.pages.each do |page|
-          xobjects = page.resources[:XObject]
+          next unless (xobjects = page.resources[:XObject])
           xobjects.each do |key, obj|
             next if used_refs[obj]
             xobjects.delete(key)

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]},

data/lib/hexapdf/type/annotation.rb

@@ -78,6 +78,25 @@ module HexaPDF
           self[:D] || self[:N]
         end
 
+        APPEARANCE_TYPE_TO_KEY = {normal: :N, rollover: :R, down: :D}.freeze #:nodoc:
+
+        # Sets the appearance of the given appearance +type+, which can either be :normal, :rollover
+        # or :down, to +appearance+.
+        #
+        # If the +state_name+ argument is provided, the +appearance+ is stored under the
+        # +state_name+ key in a sub-dictionary of the appearance.
+        def set_appearance(appearance, type: :normal, state_name: nil)
+          key = APPEARANCE_TYPE_TO_KEY.fetch(type) do
+            raise ArgumentError, "Invalid value for type specified: #{type.inspect}"
+          end
+          if state_name
+            self[key] = {} unless value[key].kind_of?(Hash)
+            self[key][state_name] = appearance
+          else
+            self[key] = appearance
+          end
+        end
+
       end
 
       # Border style dictionary used by various annotation types.
@@ -132,15 +151,16 @@ module HexaPDF
       # Returns the annotation's appearance stream of the given type (:normal, :rollover, or :down)
       # or +nil+ if it doesn't exist.
       #
-      # The appearance state is taken into account if necessary.
-      def appearance(type = :normal)
+      # The appearance state in /AS or the one provided via +state_name+ is taken into account if
+      # necessary.
+      def appearance(type: :normal, state_name: self[:AS])
         entry = appearance_dict&.send("#{type}_appearance")
         if entry.kind_of?(HexaPDF::Dictionary) && !entry.kind_of?(HexaPDF::Stream)
-          entry = entry[self[:AS]]
+          entry = entry[state_name]
         end
         return unless entry.kind_of?(HexaPDF::Stream)
 
-        if entry.type == :XObject && entry[:Subtype] == :Form
+        if entry.type == :XObject && entry[:Subtype] == :Form && !entry.instance_of?(HexaPDF::Stream)
           entry
         elsif (entry[:Type].nil? || entry[:Type] == :XObject) &&
             (entry[:Subtype].nil? || entry[:Subtype] == :Form) && entry[:BBox]
@@ -149,6 +169,19 @@ module HexaPDF
       end
       alias appearance? appearance
 
+      # Creates an empty appearance stream (a Form XObject) of the given type (:normal, :rollover,
+      # or :down) and returns it. If an appearance stream already exist, it is overwritten.
+      #
+      # If there can be multiple appearance streams for the annotation, use the +state_name+
+      # argument to provide the appearance state name.
+      def create_appearance(type: :normal, state_name: self[:AS])
+        xobject = document.add({Type: :XObject, Subtype: :Form,
+                                BBox: [0, 0, self[:Rect].width, self[:Rect].height]})
+        self[:AP] ||= {}
+        appearance_dict.set_appearance(xobject, type: type, state_name: state_name)
+        xobject
+      end
+
       private
 
       # Helper method for bit field getter access.