hexapdf 0.28.0 → 0.29.0

data/lib/hexapdf/digital_signature/signatures.rb

@@ -0,0 +1,210 @@
+# -*- 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-2022 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 'stringio'
+require 'hexapdf/digital_signature'
+require 'hexapdf/error'
+
+module HexaPDF
+  module DigitalSignature
+
+    # This class provides methods for interacting with digital signatures of a PDF file. Use it
+    # through HexaPDF::Document#signatures.
+    class Signatures
+
+      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 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.
+      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"
+        end
+        handler.new(**attributes)
+      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. To modify the signed document (e.g. for adding another
+      # signature) create a new document based on the given 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
+      #     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
+          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
+        handler.finalize_objects(signature_field, signature)
+        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
+
+        io = if file_or_io.kind_of?(String)
+               File.open(file_or_io, 'wb+')
+             else
+               file_or_io
+             end
+
+        # Save the current state so that we can determine the correct /ByteRange value and set the
+        # values
+        start_xref, section = @document.write(io, incremental: true, **write_options)
+        signature_offset, signature_length = Signing.locate_signature_dict(section, start_xref,
+                                                                           signature.oid)
+        io.pos = signature_offset
+        signature_data = io.read(signature_length)
+
+        io.seek(0, IO::SEEK_END)
+        file_size = io.pos
+
+        # 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_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
+        io.pos = signature_offset
+        io.write(signature_data)
+        signature[:Contents] = handler.sign(io, signature[:ByteRange].value)
+
+        # And now replace the /Contents value
+        Signing.replace_signature_contents(signature_data, signature[:Contents])
+        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/digital_signature/signing/default_handler.rb

@@ -0,0 +1,317 @@
+# -*- 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-2022 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'
+require 'hexapdf/version'
+require 'stringio'
+
+module HexaPDF
+  module DigitalSignature
+    module Signing
+
+      # This is the default signing handler which provides the ability to sign a document with the
+      # adbe.pkcs7.detached or ETSI.CAdES.detached algorithms. It is registered under the :default
+      # name.
+      #
+      # == Usage
+      #
+      # The signing handler is used by default by all methods that need a signing handler. Therefore
+      # it is usually only necessary to provide the actual attribute values.
+      #
+      # *Note*: Currently only RSA is supported, DSA and ECDSA are not. See the examples below for
+      # how to handle them using external signing.
+      #
+      #
+      # == CMS and PAdES Signatures
+      #
+      # The handler supports the older standard of CMS signatures as well as the newer PAdES
+      # signatures specified in PDF 2.0. By default, CMS signatures are created but this can be
+      # changed by setting #signature_type to :pades.
+      #
+      # When creating PAdES signatures the following two PAdES baseline signatures are supported:
+      # B-B and B-T. The difference between those two is that a timestamp handler was defined for
+      # B-T compatibility.
+      #
+      #
+      # == Signing Modes - Internal, External, External/Asynchronous
+      #
+      # This handler provides two ways to create the CMS signed-data structure required by
+      # Signatures#add:
+      #
+      # * By providing the signing certificate together with the signing key and the certificate
+      #   chain, HexaPDF itself does the signing *internally*. It is the preferred way if all the
+      #   needed information is available.
+      #
+      #   Assign the respective data to the #certificate, #key and #certificate_chain attributes.
+      #
+      # * By using an *external signing mechanism*, a callable object assigned to #external_signing.
+      #   Here the actual signing happens "outside" of HexaPDF, for example, in custom code or even
+      #   asynchronously. This is needed in case the signing key is not directly available but only
+      #   an interface to it (e.g. when dealing with a HSM).
+      #
+      #   Depending on whether #certificate is set the signing happens differently:
+      #
+      #   * If #certificate is not set, the callable object is used instead of #sign, so it needs to
+      #     accept the same arguments as #sign and needs to return a complete, DER-serialized CMS
+      #     signed data object.
+      #
+      #   * If #certificate is set, the CMS signed data object is created by HexaPDF. The
+      #     callable #external_signing object is called with the used digest algorithm and the
+      #     already digested data which needs to be signed (but *not* digested) and the signature
+      #     returned.
+      #
+      #   If the signing process needs to be *asynchronous*, make sure to set the #signature_size
+      #   appropriately, return an empty string during signing and later use
+      #   Signatures.embed_signature to embed the actual signature.
+      #
+      #
+      # == Optional Data
+      #
+      # Besides the required data, some optional attributes can also be specified:
+      #
+      # * Reason, location and contact information
+      # * Making the signature a certification signature by applying the DocMDP transform method and
+      #   a DoCMDP permission
+      #
+      #
+      # == Examples
+      #
+      #   # Signing using certificate + key
+      #   document.sign("output.pdf", certificate: my_cert, key: my_key,
+      #                 certificate_chain: my_chain)
+      #
+      #   # Signing using an external mechanism without certificate set
+      #   signing_proc = lambda do |io, byte_range|
+      #     io.pos = byte_range[0]
+      #     data = io.read(byte_range[1])
+      #     io.pos = byte_range[2]
+      #     data << io.read(byte_range[3])
+      #     signing_service.pkcs7_sign(data).to_der
+      #   end
+      #   document.sign("output.pdf", signature_size: 10_000, external_signing: signing_proc)
+      #
+      #   # Signing using external mechanism with certificate set
+      #   signing_proc = lambda do |digest_method, hash|
+      #     signing_service.sign_raw(digest_method, hash)
+      #   end
+      #   document.sign("output.pdf", certificate: my_cert, certificate_chain: my_chain,
+      #                 external_signing: signing_proc)
+      #
+      #   # Signing with DSA or ECDSA certificate/keys
+      #   signing_proc = lambda do |io, byte_range|
+      #     io.pos = byte_range[0]
+      #     data = io.read(byte_range[1])
+      #     io.pos = byte_range[2]
+      #     data << io.read(byte_range[3])
+      #     OpenSSL::PKCS7.sign(certificate, key, data, certificate_chain,
+      #                         OpenSSL::PKCS7::DETACHED | OpenSSL::PKCS7::BINARY).to_der
+      #   end
+      #   document.sign("output.pdf", signature_size: 10_000, external_signing: signing_proc)
+      #
+      #
+      # == Implementing a Signing Handler
+      #
+      # This class also serves as an example on how to create a custom handler: The public methods
+      # #signature_size, #finalize_objects and #sign are used by the digital signature algorithm.
+      # See their descriptions for details.
+      #
+      # 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.
+        #
+        # If the certificate is provided, HexaPDF creates the signature object. Otherwise the
+        # #external_signing callable object has to create it.
+        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.
+        attr_accessor :key
+
+        # The certificate chain that should be embedded in the PDF; usually contains all
+        # certificates up to the root certificate.
+        attr_accessor :certificate_chain
+
+        # The digest algorithm that should be used when creating the signature.
+        #
+        # See SignedDataCreator#digest_algorithm for the default value (if nothing is set) and for
+        # the allowed values.
+        attr_accessor :digest_algorithm
+
+        # The timestamp handler that should be used for timestamping the signature.
+        #
+        # If this attribute is set, a timestamp token is embedded into the CMS object.
+        attr_accessor :timestamp_handler
+
+        # A callable object for custom signing mechanisms.
+        #
+        # The callable object has two different uses depending on whether #certificate is set:
+        #
+        # * If #certificate is not set, it fulfills the same role as the #sign method and needs to
+        #   conform to that interface.
+        #
+        # * 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.
+        attr_accessor :external_signing
+
+        # 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 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.
+        #
+        # The size needs to be at least as big as the final signature, otherwise signing results in
+        # an error.
+        attr_writer :signature_size
+
+        # The type of signature to be written (i.e. the value of the /SubFilter key).
+        #
+        # The value can either be :cms (the default; uses a detached CMS signature) or :pades
+        # (uses an ETSI CAdES compatible signature).
+        attr_accessor :signature_type
+
+        # The DocMDP permissions that should be set on the document.
+        #
+        # See #doc_mdp_permissions=
+        attr_reader :doc_mdp_permissions
+
+        # Creates a new DefaultHandler instance with the given attributes.
+        def initialize(**arguments)
+          @signature_size = nil
+          @signature_type = :cms
+          arguments.each {|name, value| send("#{name}=", value) }
+        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 serialized signature that should be reserved.
+        #
+        # If a custom size is set using #signature_size=, it used. Otherwise the size is determined
+        # by using #sign to sign an empty string.
+        def signature_size
+          @signature_size || sign(StringIO.new, [0, 0, 0, 0]).size
+        end
+
+        # Finalizes the signature field as well as the signature dictionary before writing.
+        def finalize_objects(_signature_field, signature)
+          signature[:Filter] = :'Adobe.PPKLite'
+          signature[:SubFilter] = (signature_type == :pades ? :'ETSI.CAdES.detached' : :'adbe.pkcs7.detached')
+          signature[:M] = Time.now
+          signature[:Reason] = reason if reason
+          signature[:Location] = location if location
+          signature[:ContactInfo] = contact_info if contact_info
+          signature[:Prop_Build] = {App: {Name: :HexaPDF, REx: HexaPDF::VERSION}}
+
+          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: :SHA256,
+                              TransformParams: params})
+            signature[:Reference] = [sigref]
+            (doc.catalog[:Perms] ||= {})[:DocMDP] = signature
+          end
+        end
+
+        # Returns the DER serialized CMS signed data object containing the signature for the given
+        # IO byte ranges.
+        #
+        # The +byte_range+ argument is an array containing four numbers [offset1, length1, offset2,
+        # length2]. The offset numbers are byte positions in the +io+ argument and the to-be-signed
+        # data can be determined by reading length bytes at the offsets.
+        def sign(io, byte_range)
+          if certificate
+            io.pos = byte_range[0]
+            data = io.read(byte_range[1])
+            io.pos = byte_range[2]
+            data << io.read(byte_range[3])
+            SignedDataCreator.create(data,
+                                     type: signature_type,
+                                     certificate: certificate, key: key,
+                                     digest_algorithm: digest_algorithm,
+                                     timestamp_handler: timestamp_handler,
+                                     certificates: certificate_chain, &external_signing).to_der
+          else
+            external_signing.call(io, byte_range)
+          end
+        end
+
+      end
+
+    end
+  end
+end