hexapdf 0.28.0 → 0.31.0

data/lib/hexapdf/digital_signature/handler.rb

@@ -0,0 +1,138 @@
+# -*- 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 'hexapdf/digital_signature/verification_result'
+
+module HexaPDF
+  module DigitalSignature
+
+    # The base signature handler providing common functionality.
+    #
+    # Specific signature handler need to override methods if necessary and implement the needed
+    # ones that don't have a default implementation.
+    class Handler
+
+      # The signature dictionary used by the handler.
+      attr_reader :signature_dict
+
+      # Creates a new signature handler for the given signature dictionary.
+      def initialize(signature_dict)
+        @signature_dict = signature_dict
+      end
+
+      # Returns the common name of the signer (/Name field of the signature dictionary).
+      def signer_name
+        @signature_dict[:Name]
+      end
+
+      # Returns the time of signing (/M field of the signature dictionary).
+      def signing_time
+        @signature_dict[:M]
+      end
+
+      # Returns the certificate chain.
+      #
+      # Needs to be implemented by specific handlers.
+      def certificate_chain
+        raise "Needs to be implemented by specific handlers"
+      end
+
+      # Returns the certificate used for signing.
+      #
+      # Needs to be implemented by specific handlers.
+      def signer_certificate
+        raise "Needs to be implemented by specific handlers"
+      end
+
+      # Verifies general signature properties and prepares the provided OpenSSL::X509::Store
+      # object for use by concrete implementations.
+      #
+      # Needs to be called by specific handlers.
+      def verify(store, allow_self_signed: false)
+        result = VerificationResult.new
+        check_certified_signature(result)
+        verify_signing_time(result)
+        store.verify_callback =
+          store_verification_callback(result, allow_self_signed: allow_self_signed)
+        result
+      end
+
+      protected
+
+      # Verifies that the signing time was within the validity period of the signer certificate.
+      def verify_signing_time(result)
+        time = signing_time
+        cert = signer_certificate
+        if time && cert && (time < cert.not_before || time > cert.not_after)
+          result.log(:error, "Signer certificate not valid at signing time")
+        end
+      end
+
+      DOCMDP_PERMS_MESSAGE_MAP = { # :nodoc:
+        1 => "No changes allowed",
+        2 => "Form filling and signing allowed",
+        3 => "Form filling, signing and annotation manipulation allowed",
+      }
+
+      # Sets an informational message on +result+ whether the signature is a certified signature.
+      def check_certified_signature(result)
+        sigref = signature_dict[:Reference]&.find {|ref| ref[:TransformMethod] == :DocMDP }
+        if sigref && signature_dict.document.catalog[:Perms]&.[](:DocMDP) == signature_dict
+          perms = sigref[:TransformParams]&.[](:P) || 2
+          result.log(:info, "Certified signature (#{DOCMDP_PERMS_MESSAGE_MAP[perms]})")
+        end
+      end
+
+      # Returns the block that should be used as the OpenSSL::X509::Store verification callback.
+      #
+      # +result+:: The VerificationResult object that should be updated if problems are found.
+      #
+      # +allow_self_signed+:: Specifies whether self-signed certificates are allowed.
+      def store_verification_callback(result, allow_self_signed: false)
+        lambda do |_success, context|
+          if context.error == OpenSSL::X509::V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT ||
+              context.error == OpenSSL::X509::V_ERR_SELF_SIGNED_CERT_IN_CHAIN
+            result.log(allow_self_signed ? :info : :error, "Self-signed certificate found")
+          end
+
+          true
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/digital_signature/pkcs1_handler.rb

@@ -0,0 +1,96 @@
+# -*- 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/digital_signature/handler'
+
+module HexaPDF
+  module DigitalSignature
+
+    # 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.
+    #
+    # See: PDF1.7/2.0 s12.8.3.2
+    class PKCS1Handler < Handler
+
+      # Returns the certificate chain.
+      def certificate_chain
+        return [] unless signature_dict.key?(:Cert)
+        [signature_dict[:Cert]].flatten.map {|str| OpenSSL::X509::Certificate.new(str) }
+      end
+
+      # Returns the signer certificate (an instance of OpenSSL::X509::Certificate).
+      def signer_certificate
+        certificate_chain.first
+      end
+
+      # Verifies the signature using the provided OpenSSL::X509::Store object.
+      def verify(store, allow_self_signed: false)
+        result = super
+
+        signer_certificate = self.signer_certificate
+        certificate_chain = self.certificate_chain
+
+        if certificate_chain.empty?
+          result.log(:error, "No certificates for verification found")
+          return result
+        end
+
+        signature = OpenSSL::ASN1.decode(signature_dict.contents)
+        if signature.tag != OpenSSL::ASN1::OCTET_STRING
+          result.log(:error, "PKCS1 signature object invalid, octet string expected")
+          return result
+        end
+
+        store.verify(signer_certificate, certificate_chain)
+
+        if signer_certificate.public_key.verify(OpenSSL::Digest.new('SHA1'),
+                                                signature.value, signature_dict.signed_data)
+          result.log(:info, "Signature valid")
+        else
+          result.log(:error, "Signature verification failed")
+        end
+
+        result
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/{type → digital_signature}/signature.rb

@@ -39,7 +39,7 @@ require 'hexapdf/dictionary'
 require 'hexapdf/error'
 
 module HexaPDF
-  module Type
+  module DigitalSignature
 
     # Represents a digital signature that is used to authenticate a user and the contents of the
     # document.
@@ -53,14 +53,9 @@ module HexaPDF
     # By defining a custom signature handler one is able to also customize the signature
     # verification.
     #
-    # See: PDF1.7 s12.8.1, PDF2.0 s12.8.1, HexaPDF::Type::AcroForm::SignatureField
+    # See: PDF1.7/2.0 s12.8.1, HexaPDF::Type::AcroForm::SignatureField
     class Signature < Dictionary
 
-      autoload :Handler, 'hexapdf/type/signature/handler'
-      autoload :AdbeX509RsaSha1, 'hexapdf/type/signature/adbe_x509_rsa_sha1'
-      autoload :AdbePkcs7Detached, 'hexapdf/type/signature/adbe_pkcs7_detached'
-      autoload :VerificationResult, 'hexapdf/type/signature/verification_result'
-
       # Represents a transform parameters dictionary.
       #
       # The allowed fields depend on the transform method, so not all fields are available all the
@@ -122,7 +117,7 @@ module HexaPDF
 
       # Represents a signature reference dictionary.
       #
-      # See: PDF1.7 s12.8.1, PDF2.0 s12.8.1, HexaPDF::Type::Signature
+      # See: PDF1.7/2.0 s12.8.1, HexaPDF::DigitalSignature::Signature
       class SignatureReference < Dictionary
 
         define_type :SigRef

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