hexapdf 0.28.0 → 0.31.0

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

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

@@ -0,0 +1,308 @@
+# -*- 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/error'
+
+module HexaPDF
+  module DigitalSignature
+    module Signing
+
+      # This class is used for creating a CMS SignedData binary data object, as needed for PDF
+      # signing.
+      #
+      # OpenSSL already provides the ability to access, sign and create such CMS objects but is
+      # limited in what it offers in terms of data added to it. Since HexaPDF needs to follow the
+      # PDF standard, it needs control over the created structure so as to make it compatible with
+      # the various requirements.
+      #
+      # As the created CMS object is only meant to be used in the context of PDF signing, it also
+      # restricts certain things, like allowing only a single signer.
+      #
+      # Additionally, only RSA signatures are currently supported!
+      #
+      # See: PDF1.7/2.0 s12.8.3.3, PDF2.0 s12.8.3.4, RFC5652, ETSI TS 102 778 Parts 1-4
+      class SignedDataCreator
+
+        # Creates a SignedDataCreator, sets the given attributes if they are not nil and then calls
+        # #create with the given data, type and block.
+        def self.create(data, type: :cms, **attributes, &block)
+          instance = new
+          attributes.each {|key, value| instance.send("#{key}=", value) unless value.nil? }
+          instance.create(data, type: type, &block)
+        end
+
+        # The OpenSSL certificate object which is used to sign the data.
+        attr_accessor :certificate
+
+        # The OpenSSL key object which is used for signing. Needs to correspond to #certificate.
+        #
+        # If the key is not set, a block for signing will need to be provided to #sign.
+        attr_accessor :key
+
+        # Array of additional OpenSSL certificate objects that should be included.
+        #
+        # Should include all certificates of the hierarchy of the signing certificate.
+        attr_accessor :certificates
+
+        # The digest algorithm that should be used. Defaults to 'sha256'.
+        #
+        # Allowed values: sha256, sha384, sha512.
+        attr_accessor :digest_algorithm
+
+        # The timestamp handler instance that should be used for timestamping.
+        attr_accessor :timestamp_handler
+
+        # Creates a new SignedData object.
+        #
+        # Use the attribute accessor methods to set the required attributes.
+        def initialize
+          @certificate = nil
+          @key = nil
+          @certificates = []
+          @digest_algorithm = 'sha256'
+          @timestamp_handler = nil
+        end
+
+        # Creates a CMS SignedData binary data object for the given data using the set attributes
+        # and returns it in DER-serialized form.
+        #
+        # If the #key attribute is not set, the digest algorithm and the already digested data to be
+        # signed is yielded and the block needs to return the signature.
+        #
+        # +type+::
+        #     The type can either be :cms when creating standard PDF CMS signatures or :pades when
+        #     creating PAdES compatible signatures. PAdES signatures are part of PDF 2.0.
+        def create(data, type: :cms, &block) # :yield: digested_data
+          signed_attrs = create_signed_attrs(data, signing_time: (type == :cms))
+          signature = digest_and_sign_data(set(*signed_attrs.value).to_der, &block)
+          unsigned_attrs = create_unsigned_attrs(signature)
+
+          signer_info = create_signer_info(signature, signed_attrs, unsigned_attrs)
+          signed_data = create_signed_data(signer_info)
+          create_content_info(signed_data)
+        end
+
+        private
+
+        # Creates the set of signed attributes for the signer information structure.
+        def create_signed_attrs(data, signing_time: true)
+          set(
+            attribute('content-type', oid('id-data')),
+            (attribute('id-signingTime', utc_time(Time.now.utc)) if signing_time),
+            attribute(
+              'message-digest',
+              binary(OpenSSL::Digest.digest(@digest_algorithm, data))
+            ),
+            attribute(
+              'id-aa-signingCertificateV2',
+              sequence( # SigningCertificateV2
+                sequence( # Seq of ESSCertIDv2
+                  sequence( # ESSCertIDv2
+                    #TODO: Does not validate on ETSI checker if used, doesn't matter if SHA256 or 512
+                    #oid('sha512'),
+                    binary(OpenSSL::Digest.digest('sha256', @certificate.to_der)), # certHash
+                    sequence(                                      # issuerSerial
+                      sequence(                                    #  issuer
+                        implicit(4, sequence(@certificate.issuer)) #   choice 4 directoryName
+                      ),
+                      integer(@certificate.serial)                 #  serial
+                    )
+                  )
+                )
+              )
+            )
+          )
+        end
+
+        # Creates the set of unsigned attributes for the signer information structure.
+        def create_unsigned_attrs(signature)
+          attrs = set
+          if @timestamp_handler
+            time_stamp_token = @timestamp_handler.sign(StringIO.new(signature),
+                                                       [0, signature.size, 0, 0])
+            attrs.value << attribute('id-aa-timeStampToken', time_stamp_token)
+          end
+          attrs.value.empty? ? nil : attrs
+        end
+
+        # Creates a single attribute for use in the (un)signed attributes set.
+        def attribute(name, value)
+          sequence(
+            oid(name), # attrType
+            set(value) # attrValues
+          )
+        end
+
+        # Digests the data and then signs it using the assigned key, or if the key is not available,
+        # by yielding to the caller.
+        def digest_and_sign_data(data)
+          hash = OpenSSL::Digest.digest(@digest_algorithm, data)
+          if @key
+            @key.sign_raw(@digest_algorithm, hash)
+          else
+            yield(@digest_algorithm, hash)
+          end
+        end
+
+        # Creates a signer information structure containing the actual meat of the whole CMS object.
+        def create_signer_info(signature, signed_attrs, unsigned_attrs = nil)
+          certificate_pkey_algorithm = @certificate.public_key.oid
+          signature_algorithm = if certificate_pkey_algorithm == 'rsaEncryption'
+                                  sequence(               # signatureAlgorithm
+                                    oid('rsaEncryption'), #   algorithmID
+                                    null                  #   params
+                                  )
+                                else
+                                  raise HexaPDF::Error, "Unsupported key type/signature algorithm"
+                                end
+
+          sequence(
+            integer(1),                    # version
+            sequence(                      # sid (choice: issuerAndSerialNumber)
+              @certificate.issuer,         #   issuer
+              integer(@certificate.serial) #   serial
+            ),
+            sequence(                      # digestAlgorithm
+              oid(@digest_algorithm),      #   algorithmID
+              null                         #   params
+            ),
+            implicit(0, signed_attrs),     # signedAttrs 0 implicit
+            signature_algorithm,           # signatureAlgorithm
+            binary(signature),             # signature
+            (implicit(1, unsigned_attrs) if unsigned_attrs) # unsignedAttrs 1 implicit
+          )
+        end
+
+        # Creates the signed data structure which is the actual content of the CMS object.
+        def create_signed_data(signer_info)
+          certificates = set(*[@certificate, @certificates].flatten)
+
+          sequence(
+            integer(1),                 # version
+            set(                        # digestAlgorithms
+              sequence(                 #   digestAlgorithm
+                oid(@digest_algorithm), #     algorithmID
+                null                    #     params
+              )
+            ),
+            sequence(                   # encapContentInfo (detached signature)
+              oid('id-data')            #   eContentType
+            ),
+            implicit(0, certificates),  # certificates 0 implicit
+            set(                        # signerInfos
+              signer_info               #   signerInfo
+            )
+          )
+        end
+
+        # Creates the content info structure which is the main structure containing everything else.
+        def create_content_info(signed_data)
+          signed_data.tag = 0
+          signed_data.tagging = :EXPLICIT
+          signed_data.tag_class = :CONTEXT_SPECIFIC
+          sequence(
+            oid('id-signedData'), # contentType
+            signed_data           # content 0 explicit
+          )
+        end
+
+        # Changes the given ASN1Data object to use implicit tagging with the given +tag+ and a tag
+        # class of :CONTEXT_SPECIFIC.
+        def implicit(tag, data)
+          data.tag = tag
+          data.tagging = :IMPLICIT
+          data.tag_class = :CONTEXT_SPECIFIC
+          data
+        end
+
+        # Creates an ASN.1 set instance.
+        def set(*contents, tag: nil, tagging: nil)
+          OpenSSL::ASN1::Set.new(contents.compact, *tag, *tagging)
+        end
+
+        # Creates an ASN.1 sequence instance.
+        def sequence(*contents, tag: nil, tagging: nil)
+          OpenSSL::ASN1::Sequence.new(contents.compact, *tag, *tagging)
+        end
+
+        # Mapping of ASN.1 object ID names to object ID strings.
+        OIDS = {
+          'content-type' => '1.2.840.113549.1.9.3',
+          'message-digest' => '1.2.840.113549.1.9.4',
+          'id-data' => '1.2.840.113549.1.7.1',
+          'id-signedData' => '1.2.840.113549.1.7.2',
+          'id-signingTime' => '1.2.840.113549.1.9.5',
+          'sha256' => '2.16.840.1.101.3.4.2.1',
+          'sha384' => '2.16.840.1.101.3.4.2.2',
+          'sha512' => '2.16.840.1.101.3.4.2.3',
+          'rsaEncryption' => '1.2.840.113549.1.1.1',
+          'id-aa-signingCertificate' => '1.2.840.113549.1.9.16.2.12',
+          'id-aa-timeStampToken' => '1.2.840.113549.1.9.16.2.14',
+          'id-aa-signingCertificateV2' => '1.2.840.113549.1.9.16.2.47',
+        }
+
+        # Creates an ASN.1 object ID instance for the given object ID name.
+        def oid(name)
+          OpenSSL::ASN1::ObjectId.new(OIDS[name])
+        end
+
+        # Creates an ASN.1 octet string instance.
+        def binary(str)
+          OpenSSL::ASN1::OctetString.new(str)
+        end
+
+        # Creates an ASN.1 integer instance.
+        def integer(int)
+          OpenSSL::ASN1::Integer.new(int)
+        end
+
+        # Creates an ASN.1 UTC time instance.
+        def utc_time(value)
+          OpenSSL::ASN1::UTCTime.new(value)
+        end
+
+        # Creates an ASN.1 null instance.
+        def null
+          OpenSSL::ASN1::Null.new(nil)
+        end
+
+      end
+
+    end
+  end
+end