hanko_xml 0.1.0 → 0.2.0

data/lib/hanko_xml/xades/verifier.rb

@@ -11,11 +11,30 @@ module HankoXml
     class Verification < HankoXml::Verification
       # @return [SignedProperties, nil] Only when #valid?.
       attr_reader :signed_properties
-
-      def initialize(signed_properties: nil, **attributes)
+      # @return [Array<SignatureTimeStamp>, nil] The verified SignatureTimeStamps (#163), in document order;
+      #   empty when there are none, nil unless #valid? or with timestamps: :ignore.
+      attr_reader :signature_timestamps
+      # @return [LongTermValidation, nil] The XAdES-LT validation (#168): only when #valid? and the signature
+      #   carries CertificateValues or RevocationValues that were checked.
+      attr_reader :long_term_validation
+      # @return [Array<SignatureTimeStamp>, nil] The verified xades141:ArchiveTimeStamps (#169), in document
+      #   order; empty when there are none, nil unless #valid? or with timestamps: :ignore.
+      attr_reader :archive_timestamps
+
+      def initialize(signed_properties: nil, signature_timestamps: nil, long_term_validation: nil,
+                     archive_timestamps: nil, **attributes)
         @signed_properties = signed_properties
+        @signature_timestamps = signature_timestamps&.freeze
+        @long_term_validation = long_term_validation
+        @archive_timestamps = archive_timestamps&.freeze
         super(**attributes)
       end
+
+      # The earliest verified SignatureTimeStamp time: when a trusted third
+      # party saw this signature at the latest. Nil without one.
+      def timestamp_time
+        signature_timestamps&.map(&:time)&.min
+      end
     end
 
     # Verifies a XAdES-B signature (#58): the XML-DSig signature through
@@ -31,14 +50,44 @@ module HankoXml
     # Reads XAdES 1.3.2 and the older 1.2.2 and 1.1.1 namespaces (#86); the
     # whole signature must use one.
     #
+    # XAdES-T (#163): every <xades:SignatureTimeStamp> in the signature's
+    # UnsignedSignatureProperties must verify against the TSA trust
+    # (tsa_store: / tsa_certificates:), kept apart from the signer's. A
+    # timestamp that does not verify fails the signature (fail closed).
+    # Xades::Locator finds QualifyingProperties and its unsigned containers.
+    #
+    # XAdES-LT (#168): when the signature embeds CertificateValues or
+    # RevocationValues, the signing certificate is validated at the time of
+    # the earliest verified SignatureTimeStamp: XML-DSig trust (chain,
+    # validity dates) at that time, then revocation evidence for every
+    # certificate below the trust anchor from the embedded CRLs and OCSP
+    # responses (Xades::LongTermCheck). A certificate that has expired since
+    # still verifies; embedded data that does not hold fails (fail closed).
+    # XAdES-LTA (#169): every xades141:ArchiveTimeStamp must verify too, over
+    # the EN 319 132-1 input (Xades::ArchiveTimeStampCheck), against the same
+    # TSA trust; fail closed, and not read with timestamps: :ignore.
+    #
     # Needs certificate-based trust (certificate:, certificates:, store:), and
     # Nokogiri: the signed properties are read from the DOM (#102).
-    # Unsigned properties (XAdES-T/LT/LTA) are ignored: #81, #82.
     class Verifier < HankoXml::Verifier # rubocop:disable Metrics/ClassLength
+      TIMESTAMP_MODES = %i[verify require ignore].freeze
+      LONG_TERM_MODES = %i[verify require ignore].freeze
+
       # @param signature_policy [SignaturePolicy, Hash, :implied, nil] When given, the signed
       #   SignaturePolicyIdentifier must be exactly this.
+      # @param timestamps [Symbol] :verify (default) checks every SignatureTimeStamp present; :require also
+      #   fails a signature without one; :ignore does not read them, the XAdES-B behavior.
+      # @param tsa_store [OpenSSL::X509::Store, nil] Trust for the TSAs, not the signer.
+      # @param tsa_certificates [Array<OpenSSL::X509::Certificate, String, Key>, nil] Trusted TSA roots or
+      #   certificates, instead of tsa_store:.
+      # @param long_term [Symbol, nil] :verify checks embedded XAdES-LT values when present; :require also
+      #   fails a signature without them; :ignore does not read them. nil (default) is :verify, or :ignore with
+      #   timestamps: :ignore, since the validation time comes from a SignatureTimeStamp.
+      # @param revocation_grace [Numeric] Seconds an embedded CRL or OCSP response may predate the validation
+      #   time and still count as fresh. 0 (default): it must be issued at or after it.
       # All other keywords are {HankoXml::Verifier}'s.
-      def initialize(signature_policy: nil, **options)
+      def initialize(signature_policy: nil, timestamps: :verify, tsa_store: nil, tsa_certificates: nil,
+                     long_term: nil, revocation_grace: 0, **options)
         Dom.require!("HankoXml::Xades::Verifier")
         if options[:key] || options[:keys]
           raise HankoXml::ConfigurationError,
@@ -47,6 +96,12 @@ module HankoXml
         end
 
         @expected_signature_policy = coerce_signature_policy(signature_policy)
+        @timestamps = coerce_timestamps(timestamps)
+        @tsa_store = coerce_tsa_store(tsa_store, tsa_certificates)
+        @long_term = coerce_long_term(long_term)
+        @revocation_grace = coerce_revocation_grace(revocation_grace)
+        # Kept to verify the XML-DSig signature again at the validation time.
+        @options = options.freeze
         super(**options)
       end
 
@@ -59,25 +114,109 @@ module HankoXml
       end
 
       def verify(xml)
-        xades(super)
+        as_xades(super)
       end
 
       def verify_all(xml)
-        super.map { |verification| xades(verification) }
+        super.map { |verification| as_xades(verification) }
       end
 
       private
 
-      def xades(verification)
+      # Every signature verified goes through here, with the bytes and the
+      # index the native layer used, which the timestamp checks reuse.
+      #
+      # With XAdES-LT values, the SignatureTimeStamps are verified first, as
+      # their earliest time is when the signing certificate is validated
+      # (#168): the XML-DSig signature is then verified at that time.
+      def verify_single(input, index)
+        values, timestamps = long_term_plan(input, index)
+        return xades(super, input.bytes, index) unless values
+
+        time = timestamps.map(&:time).min
+        verification = xades(at_time(time, values, input, index), input.bytes, index, timestamps: timestamps)
+        return verification unless verification.valid?
+
+        validation = LongTermCheck.new(grace: @revocation_grace, clock_skew: @policy.clock_skew)
+                                  .verify(time: time, chain: long_term_chain(verification), values: values)
+        rebuild(verification, signed_properties: verification.signed_properties,
+                              signature_timestamps: verification.signature_timestamps,
+                              archive_timestamps: verification.archive_timestamps,
+                              long_term_validation: validation)
+      rescue HankoXml::XadesError, HankoXml::PolicyError => e
+        rebuild(verification || super, error: e)
+      end
+
+      # The embedded XAdES-LT values and the verified SignatureTimeStamps, or
+      # nil when there are no values to check.
+      def long_term_plan(input, index)
+        return nil if @long_term == :ignore
+
+        signature = signature_nodes(input)[index]
+        values = long_term_values(signature)
+        unless values
+          if @long_term == :require
+            fail!("long_term: :require, but the signature has no <xades:CertificateValues> or " \
+                  "<xades:RevocationValues>")
+          end
+          return nil
+        end
+
+        timestamps = signature_timestamps(signature, input.bytes, index)
+        if timestamps.empty?
+          fail!("XAdES-LT values need a verified <xades:SignatureTimeStamp> for their validation time")
+        end
+
+        [values, timestamps]
+      end
+
+      # A signature whose QualifyingProperties or unsigned containers cannot
+      # be located has no values here: the signed-properties and timestamp
+      # checks fail it on the same structure, with their own message.
+      def long_term_values(signature)
+        qualifying, ns = Locator.qualifying_properties(signature)
+        properties = Locator.unsigned_signature_properties(qualifying, ns)
+      rescue HankoXml::XadesError
+        nil
+      else
+        LongTermValues.read(properties, ns)
+      end
+
+      # The XML-DSig verification at +time+ (unless the caller fixed
+      # verification_time:), with the embedded CertificateValues as untrusted
+      # intermediates for a store: chain.
+      def at_time(time, values, input, index)
+        verifier = AtTime.new(intermediates: values.certificates, signature_policy: @expected_signature_policy,
+                              timestamps: :ignore, long_term: :ignore,
+                              **@options.merge(verification_time: verification_time || time))
+        HankoXml::Verifier.instance_method(:verify_single).bind_call(verifier, input, index)
+      end
+
+      # store: gives the chain OpenSSL validated; certificate: and
+      # certificates: pin the signing certificate itself as the anchor.
+      def long_term_chain(verification)
+        verification.certificate_chain || [verification.certificate]
+      end
+
+      # A result that never reached verify_single (no signature found).
+      def as_xades(verification)
+        verification.is_a?(Verification) ? verification : rebuild(verification)
+      end
+
+      def xades(verification, xml_bytes, index, timestamps: nil)
         return rebuild(verification) unless verification.valid?
 
         properties = signed_properties(verification)
-        rebuild(verification, signed_properties: properties)
+        timestamps ||= signature_timestamps(verification.signature_node, xml_bytes, index)
+        archives = archive_timestamps(verification, xml_bytes, index)
+        rebuild(verification, signed_properties: properties, signature_timestamps: timestamps,
+                              archive_timestamps: archives)
       rescue HankoXml::XadesError, HankoXml::PolicyError => e
         rebuild(verification, error: e)
       end
 
-      def rebuild(verification, signed_properties: nil, error: nil)
+      def rebuild(verification, signed_properties: nil, signature_timestamps: nil, long_term_validation: nil,
+                  archive_timestamps: nil, error: nil)
         Verification.new(
           valid: verification.valid? && error.nil?,
           errors: [*verification.errors, *error],
@@ -94,10 +233,153 @@ module HankoXml
           reference_element_indexes: verification.reference_element_indexes,
           reference_valid: verification.reference_valid,
           signature_element_index: verification.signature_element_index,
-          signed_properties: signed_properties
+          signed_properties: signed_properties,
+          signature_timestamps: signature_timestamps,
+          long_term_validation: long_term_validation,
+          archive_timestamps: archive_timestamps
         )
       end
 
+      # Each SignatureTimeStamp of this signature, verified (#163). Read only
+      # along the path from its own QualifyingProperties, never by a search
+      # that a wrapped element elsewhere could satisfy.
+      def signature_timestamps(signature, xml_bytes, index)
+        return nil if @timestamps == :ignore
+
+        nodes, path, xades_ns = signature_timestamp_nodes(signature)
+        if nodes.empty?
+          fail!("timestamps: :require, but the signature has no <xades:SignatureTimeStamp>") if @timestamps == :require
+          return []
+        end
+
+        unless @tsa_store
+          fail!("the signature has a <xades:SignatureTimeStamp>; pass tsa_store: or tsa_certificates: to " \
+                "verify it, or timestamps: :ignore")
+        end
+
+        nodes.each_with_index.map do |node, i|
+          SignatureTimeStampCheck.new(node, [*path, [xades_ns, "SignatureTimeStamp", i]],
+                                      ns: { "ds" => HankoXml::NS["ds"], "xades" => xades_ns },
+                                      policy: @policy, tsa_store: @tsa_store).verify(xml_bytes, index)
+        end
+      end
+
+      # Each xades141:ArchiveTimeStamp of this signature, verified (#169), read
+      # along the same path as the SignatureTimeStamps.
+      def archive_timestamps(verification, xml_bytes, index)
+        return nil if @timestamps == :ignore
+
+        signature = verification.signature_node
+        qualifying, ns = Locator.qualifying_properties(signature)
+        properties = Locator.unsigned_signature_properties(qualifying, ns)
+        nodes = properties ? properties.xpath("xades141:ArchiveTimeStamp", "xades141" => NS141).to_a : []
+        return [] if nodes.empty?
+
+        fail!("ArchiveTimeStamp is verified only with XAdES 1.3.2 QualifyingProperties") unless ns["xades"] == NS
+        unless @tsa_store
+          fail!("the signature has a <xades141:ArchiveTimeStamp>; pass tsa_store: or tsa_certificates: to " \
+                "verify it, or timestamps: :ignore")
+        end
+
+        path = Locator.unsigned_path(signature, qualifying, NS)
+        references = reference_data(verification, xml_bytes, index)
+        node_set = ArchiveTimeStampCheck.node_set_references?(verification.signature_info)
+        nodes.each_with_index.map do |node, i|
+          ArchiveTimeStampCheck.new(node, [*path, [NS141, "ArchiveTimeStamp", i]],
+                                    references: references, node_set_references: node_set,
+                                    element_paths: ArchiveTimeStampCheck.element_paths(signature, qualifying,
+                                                                                       properties, node, path),
+                                    ns: { "ds" => HankoXml::NS["ds"], "xades" => NS },
+                                    policy: @policy, tsa_store: @tsa_store).verify(xml_bytes, index)
+        end
+      end
+
+      # Each SignedInfo Reference's data as xmlsec digested it, verifying the
+      # signature again with the key that verified it.
+      def reference_data(verification, xml_bytes, index)
+        octets = Native.reference_data(xml_bytes, [verification.certificate.public_key.to_pem], native_id_attributes,
+                                       index, @referenced_documents.to_a, @policy.allows?(:transform, :xpath_filter2))
+        fail!("a Reference's data could not be read for the ArchiveTimeStamp") if octets.any?(&:nil?)
+
+        octets
+      rescue HankoXml::NativeError
+        fail!("the signature's Reference data could not be read for the ArchiveTimeStamp")
+      end
+
+      # The SignatureTimeStamp elements, the native path to their parent, and
+      # their XAdES namespace.
+      def signature_timestamp_nodes(signature)
+        qualifying, ns = Locator.qualifying_properties(signature)
+        properties = Locator.unsigned_signature_properties(qualifying, ns)
+        return [[], nil] unless properties
+
+        timestamps = properties.xpath("xades:SignatureTimeStamp", ns)
+        if timestamps.any? && ns["xades"] != NS
+          fail!("SignatureTimeStamp is verified only in the XAdES 1.3.2 namespace")
+        end
+
+        [timestamps.to_a, Locator.unsigned_path(signature, qualifying, ns["xades"]), ns["xades"]]
+      end
+
+      def coerce_long_term(value)
+        value = @timestamps == :ignore ? :ignore : :verify if value.nil?
+        unless LONG_TERM_MODES.include?(value)
+          raise HankoXml::ConfigurationError, "long_term: must be one of #{LONG_TERM_MODES.inspect}"
+        end
+        if value != :ignore && @timestamps == :ignore
+          raise HankoXml::ConfigurationError,
+                "long_term: #{value.inspect} needs SignatureTimeStamps for its validation time; " \
+                "it cannot go with timestamps: :ignore"
+        end
+        if value == :require && @tsa_store.nil?
+          raise HankoXml::ConfigurationError, "long_term: :require needs tsa_store: or tsa_certificates:"
+        end
+
+        value
+      end
+
+      def coerce_revocation_grace(value)
+        return value if value.is_a?(Numeric) && value >= 0
+
+        raise HankoXml::ConfigurationError, "revocation_grace: must be a number of seconds, 0 or more"
+      end
+
+      def coerce_timestamps(value)
+        return value if TIMESTAMP_MODES.include?(value)
+
+        raise HankoXml::ConfigurationError, "timestamps: must be one of #{TIMESTAMP_MODES.inspect}"
+      end
+
+      # The TSA trust, separate from the signer's: tsa_store: as given, or a
+      # store over tsa_certificates:.
+      def coerce_tsa_store(store, certificates)
+        raise HankoXml::ConfigurationError, "pass tsa_store: or tsa_certificates:, not both" if store && certificates
+
+        if @timestamps == :require && !store && !certificates
+          raise HankoXml::ConfigurationError, "timestamps: :require needs tsa_store: or tsa_certificates:"
+        end
+        return tsa_store_from(certificates) if store.nil?
+        return store if store.is_a?(OpenSSL::X509::Store)
+
+        raise HankoXml::ConfigurationError, "tsa_store: must be an OpenSSL::X509::Store"
+      end
+
+      def tsa_store_from(certificates)
+        return nil if certificates.nil?
+
+        list = Array(certificates)
+        raise HankoXml::ConfigurationError, "tsa_certificates: must not be empty" if list.empty?
+
+        OpenSSL::X509::Store.new.tap do |store|
+          list.each do |certificate|
+            key = HankoXml::Key.coerce(certificate)
+            raise HankoXml::ConfigurationError, "tsa_certificates: must be X.509 certificates" unless key.certificate?
+
+            store.add_cert(key.to_openssl)
+          end
+        end
+      end
+
       def signed_properties(verification)
         node, ns = signed_properties_node(verification)
         signature_properties = node.at_xpath("xades:SignedSignatureProperties", ns)
@@ -122,7 +404,7 @@ module HankoXml
       # with.
       def signed_properties_node(verification)
         info, reference = signed_properties_reference(verification)
-        qualifying, ns = qualifying_properties(verification.signature_node)
+        qualifying, ns = Locator.qualifying_properties(verification.signature_node)
 
         type_namespace = VERSIONED_SIGNED_PROPERTIES_TYPES[info.type]
         if type_namespace && type_namespace != ns["xades"]
@@ -153,22 +435,6 @@ module HankoXml
         pairs.first
       end
 
-      # This signature's single QualifyingProperties, in any XAdES namespace,
-      # and the namespaces to read it with.
-      def qualifying_properties(signature)
-        signature_id = signature["Id"].to_s
-        fail!("the <Signature> has no Id for QualifyingProperties to target") if signature_id.empty?
-
-        qualifying = signature.xpath("ds:Object/*[local-name()='QualifyingProperties']", "ds" => HankoXml::NS["ds"])
-                              .select { |node| NAMESPACES.include?(node.namespace&.href) }
-        fail!("a XAdES signature has exactly one <xades:QualifyingProperties>") unless qualifying.size == 1
-
-        qualifying = qualifying.first
-        fail!("<xades:QualifyingProperties> does not target this <Signature>") unless targets?(qualifying, signature_id)
-
-        [qualifying, { "ds" => HankoXml::NS["ds"], "xades" => qualifying.namespace.href }]
-      end
-
       # By its Type, or, with no Type (as some 1.2.2 signatures write it), by
       # what xmlsec resolved and digested: a SignedProperties element in a
       # XAdES namespace. Never by the URI text (#86).
@@ -179,16 +445,6 @@ module HankoXml
         !node.nil? && node.name == "SignedProperties" && NAMESPACES.include?(node.namespace&.href)
       end
 
-      # Target is "#" + the Signature Id. The older namespaces also had
-      # signers write the bare Id (Target="Signature"). Either way the
-      # QualifyingProperties must sit in this <Signature>'s own <Object>.
-      def targets?(qualifying, signature_id)
-        target = qualifying["Target"]
-        return true if target == "##{signature_id}"
-
-        LEGACY_NAMESPACES.include?(qualifying.namespace.href) && target == signature_id
-      end
-
       def check_signing_certificate!(signature_properties, certificate, ns)
         fail!("no certificate verified the signature, so SigningCertificate cannot be checked") unless certificate
 
@@ -314,6 +570,24 @@ module HankoXml
       def fail!(message)
         raise HankoXml::XadesError, message
       end
+
+      # The XML-DSig verification of an XAdES-LT signature (#168): embedded
+      # certificates may complete the store: chain, never be its anchor or
+      # its signing certificate.
+      #
+      # @api private
+      class AtTime < Verifier
+        def initialize(intermediates:, **options)
+          @intermediates = intermediates
+          super(**options)
+        end
+
+        private
+
+        def chain_intermediates
+          @intermediates
+        end
+      end
     end
   end
 end

data/lib/hanko_xml/xades.rb

@@ -12,6 +12,10 @@ module HankoXml
   module Xades
     NS = "http://uri.etsi.org/01903/v1.3.2#"
 
+    # XAdES 1.4.1 (EN 319 132-1), the namespace of ArchiveTimeStamp and
+    # TimeStampValidationData (#169).
+    NS141 = "http://uri.etsi.org/01903/v1.4.1#"
+
     # Earlier XAdES namespaces (TS 101 903 v1.1.1, v1.2.2) that Xades::Verifier
     # also reads (#86). Xades::Signer writes only NS.
     LEGACY_NAMESPACES = %w[http://uri.etsi.org/01903/v1.2.2# http://uri.etsi.org/01903/v1.1.1#].freeze
@@ -70,8 +74,8 @@ module HankoXml
     end
 
     # The authenticated view of a verified <xades:SignedProperties>
-    # (Xades::Verification#signed_properties). Unsigned properties
-    # (timestamps, validation data) are never read.
+    # (Xades::Verification#signed_properties). Timestamps are
+    # Xades::Verification#signature_timestamps (#163).
     SignedProperties = Struct.new(:signing_time, :signature_policy, :claimed_roles, :data_object_formats,
                                   keyword_init: true) do
       def initialize(**)
@@ -88,10 +92,17 @@ module HankoXml
     # certificate:), and optionally SignaturePolicyIdentifier, SignerRoleV2
     # and DataObjectFormat.
     #
-    # Always builds a new <Signature> (template: :build). Timestamps and
-    # validation data (XAdES-T/LT/LTA) are separate: #81, #82.
+    # With timestamper:, a XAdES-T signature (#162): an RFC 3161 token over
+    # the canonicalized <ds:SignatureValue> in a <xades:SignatureTimeStamp>.
+    #
+    # With validation_data: as well, XAdES-LT (#167): CertificateValues and
+    # RevocationValues after the SignatureTimeStamp. Xades::Augmenter adds
+    # either to a signature that already exists.
+    #
+    # Always builds a new <Signature> (template: :build).
     class Signer < HankoXml::Signer
-      attr_reader :signing_time, :signature_policy, :claimed_roles, :data_object_format
+      attr_reader :signing_time, :signature_policy, :claimed_roles, :data_object_format,
+                  :timestamper, :timestamp_canonicalization_method, :validation_data
 
       # @param certificate [Key, OpenSSL::X509::Certificate, String, Pathname] Required: SigningCertificateV2
       #   commits to it.
@@ -102,9 +113,18 @@ module HankoXml
       #   of this Signer's own references, which get an Id when they have none.
       # @param signature_id [String, nil] The <Signature> Id; generated when nil, since QualifyingProperties
       #   targets it.
+      # @param timestamper [#call, nil] Called with a DER RFC 3161 TimeStampReq, returns the TSA's DER
+      #   TimeStampResp. The library never opens a connection: the callable owns the TSA exchange.
+      # @param timestamp_digest_method [Symbol, nil] The imprint digest; nil means digest_method:.
+      # @param timestamp_canonicalization_method [Symbol] How <ds:SignatureValue> is canonicalized for the
+      #   imprint.
+      # @param validation_data [ValidationData, Hash, nil] Certificates, CRLs and OCSP responses to embed
+      #   (XAdES-LT); needs timestamper:, since B-LT builds on B-T.
       # All other keywords are {HankoXml::Signer}'s.
       def initialize(certificate: nil, signing_time: nil, signature_policy: nil, claimed_roles: [],
-                     data_object_format: nil, signature_id: nil, template: :build, **options, &block)
+                     data_object_format: nil, signature_id: nil, template: :build, timestamper: nil,
+                     timestamp_digest_method: nil, timestamp_canonicalization_method: :exc_c14n, validation_data: nil,
+                     **options, &block)
         unless template.to_sym == :build
           raise HankoXml::ConfigurationError,
                 "template: #{template.inspect} is not supported for XAdES; it always builds a new <Signature>"
@@ -117,6 +137,14 @@ module HankoXml
         @signature_policy = coerce_signature_policy(signature_policy)
         @claimed_roles = Array(claimed_roles).map { |role| role.to_s.dup.freeze }.freeze
         @data_object_format = coerce_data_object_format(data_object_format)
+        SignatureTimeStamper.check_timestamper!(timestamper)
+        @timestamper = timestamper
+        @timestamp_digest_method = timestamp_digest_method
+        @timestamp_canonicalization_method = timestamp_canonicalization_method
+        @validation_data = ValidationData.coerce(validation_data)
+        if @validation_data && !timestamper
+          raise HankoXml::ConfigurationError, "validation_data: needs timestamper: (XAdES-LT builds on XAdES-T)"
+        end
 
         super(certificate: certificate, signature_id: signature_id || "xades-#{SecureRandom.hex(8)}",
               template: :build, **options, &block)
@@ -142,8 +170,37 @@ module HankoXml
         "#{signature_id}-signedprops"
       end
 
+      # The imprint digest: timestamp_digest_method:, or else digest_method:.
+      def timestamp_digest_method
+        @timestamp_digest_method || digest_method
+      end
+
+      def signature_timestamp_id
+        "#{signature_id}-sigts"
+      end
+
+      def to_h
+        super.merge(signing_time: signing_time, signature_policy: signature_policy, claimed_roles: claimed_roles,
+                    data_object_format: data_object_format, timestamper: timestamper,
+                    timestamp_digest_method: timestamp_digest_method,
+                    timestamp_canonicalization_method: timestamp_canonicalization_method,
+                    validation_data: validation_data)
+      end
+
       private
 
+      # xmlsec has signed; before the signed values reach the caller's
+      # document, obtain the timestamp over the new SignatureValue. A failure
+      # raises before anything is written back.
+      def write_back_signature(doc, signed_bytes, index, caller_sig_node)
+        token = timestamper && SignatureTimeStamper.new(self).token(signed_bytes, index)
+        super
+        return unless token
+
+        caller_sig_node.at_xpath(SignatureTimeStamper::ENCAPSULATED_XPATH, "ds" => HankoXml::NS["ds"], "xades" => NS)
+                       .content = [token].pack("m0")
+      end
+
       def signed_properties_reference
         HankoXml::Reference.new(uri: "##{signed_properties_id}", type: SIGNED_PROPERTIES_TYPE,
                                 transforms: [:exc_c14n], digest_method: digest_method)
@@ -179,6 +236,10 @@ module HankoXml
       # Checked with the key material, after the block may have set certificate:.
       def check_key_material!
         super
+        if timestamper
+          SignatureTimeStamper.check_algorithms!(policy, digest: timestamp_digest_method,
+                                                         canonicalization: timestamp_canonicalization_method)
+        end
         return if certificate.is_a?(HankoXml::Key) && certificate.certificate?
 
         raise HankoXml::ConfigurationError, "XAdES needs certificate:, which SigningCertificateV2 commits to"
@@ -207,6 +268,7 @@ module HankoXml
 
         build_signature_properties(xades(signed, "SignedSignatureProperties"))
         build_data_object_properties(signed) if @signer.data_object_format
+        build_unsigned_properties(qualifying) if @signer.timestamper
         object
       end
 
@@ -247,6 +309,26 @@ module HankoXml
         hash.add_child(element("DigestValue")).content = policy.digest_value
       end
 
+      # SignatureTimeStamp, then any validation data (#167).
+      def build_unsigned_properties(qualifying)
+        unsigned = xades(xades(qualifying, "UnsignedProperties"), "UnsignedSignatureProperties")
+        build_signature_timestamp(unsigned)
+        @signer.validation_data&.append_to(unsigned, @xades_ns)
+      end
+
+      # The SignatureTimeStamp skeleton: the CanonicalizationMethod is in the
+      # document before signing, so xmlsec reads it to canonicalize the
+      # SignatureValue (#161), as the verifier will. No Reference covers
+      # UnsignedProperties, so filling EncapsulatedTimeStamp afterwards
+      # changes nothing signed.
+      def build_signature_timestamp(unsigned)
+        timestamp = xades(unsigned, "SignatureTimeStamp")
+        timestamp["Id"] = @signer.signature_timestamp_id
+        method = timestamp.add_child(element("CanonicalizationMethod"))
+        method["Algorithm"] = HankoXml::Algorithms.uri_for(:canonicalization, @signer.timestamp_canonicalization_method)
+        xades(timestamp, "EncapsulatedTimeStamp")
+      end
+
       def build_data_object_properties(signed)
         properties = xades(signed, "SignedDataObjectProperties")
         format = @signer.data_object_format
@@ -284,4 +366,9 @@ module HankoXml
   end
 end
 
+require_relative "xades/locator"
+require_relative "xades/timestamp"
+require_relative "xades/validation_data"
+require_relative "xades/augmenter"
+require_relative "xades/long_term"
 require_relative "xades/verifier"

data/sig/hanko_xml/native.rbs

@@ -8,5 +8,7 @@ module HankoXml
     def self.sign: (String xml_bytes, String key_pem, Array[String] cert_pems, Array[String] id_attributes, Integer index) -> String
     def self.scan: (String xml_bytes, Array[String] id_attributes, bool strict) -> Hash[Symbol, untyped]
     def self.validate_schema: (String xml_bytes, Integer index, String xsd_path) -> Array[String]
+    def self.reference_data: (String xml_bytes, Array[String] trusted_pems, Array[String] id_attributes, Integer index, Array[[String, String]] referenced_documents, bool allow_xpath_filter2) -> Array[String?]
+    def self.canonicalize: (String xml_bytes, Integer index, Array[[String, String, Integer?]] target_path, Array[[String, String, Integer?]] method_path) -> String
   end
 end