xades 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73fcbd3237d890cc28a31a94cff79c09f8fe7eadb7a0f453f8a45c78791a8d52
+  data.tar.gz: dae7a067ede1c4d6567efab5654a40bbf9d7675a4c8174cfc23f6ddfaf16231b
+SHA512:
+  metadata.gz: 4fbf97d128b02319f277d72a99e7a7891443f2f371cb62ab63d5d5f424657b72bc91c55125a936edd8686d636395fcd676a4b573a608da94079b897c23cfcade
+  data.tar.gz: 63ccb7b27ea142234fb3e8fc889ff5194d7a2f9504921c817f998c2dd26f1222218c59bc6d882286f676ab3f384e5ee9ed2577e874211c53ba4276a02ae16298

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-27
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Chris Hasinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/NOTICE

@@ -0,0 +1,12 @@
+This gem's own source code is MIT-licensed (see LICENSE.txt).
+
+The test fixtures under spec/fixtures/interop/ are vendored, unmodified, from:
+
+  signxml (https://github.com/XML-Security/signxml)
+  Copyright signxml contributors
+  Licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
+
+They are test data only (sample signed XML documents used to exercise this gem's verifier) and are
+not compiled or linked into the gem's runtime code. See spec/fixtures/interop/SOURCES.md for the
+provenance and purpose of each individual file, including further upstream lineage to the esig/dss
+project (LGPL-2.1) and the ETSI XAdES plugtests corpus.

data/README.md

@@ -0,0 +1,114 @@
+# Xades
+
+[![CI](https://github.com/khasinski/xades/actions/workflows/main.yml/badge.svg)](https://github.com/khasinski/xades/actions/workflows/main.yml)
+
+XAdES-BES / BASELINE-B (ETSI EN 319 132) XML signing and verification for pure Ruby (MRI). No
+`xmlsec1` binary, no JVM -- just [Nokogiri](https://nokogiri.org/) (XML + Exclusive C14N) and
+Ruby's built-in `openssl` (RSA / ECDSA).
+
+This exists because Ruby has never had a maintained, general-purpose XAdES gem, while several
+eIDAS-adjacent flows require one -- most concretely, **Poland's KSeF 2.0** e-invoicing system,
+where authenticating with a certificate means signing an `AuthTokenRequest` document with
+XAdES-BES (see [CIRFMF/ksef-docs](https://github.com/CIRFMF/ksef-docs)).
+
+## What this is (and isn't)
+
+Implements **XAdES-BES / BASELINE-B** only:
+
+- Enveloped signatures (the signature is inserted as the last child of the signed document's root)
+- Exclusive C14N (`http://www.w3.org/2001/10/xml-exc-c14n#`)
+- RSA-SHA256 and ECDSA-SHA256 (P-256 / P-384 / P-521), with ECDSA `SignatureValue` encoded as raw
+  `R || S` per RFC 4050/6931 -- not the DER form OpenSSL produces internally
+- `SigningCertificate` (V1) or `SigningCertificateV2` (default; RFC 5035 `IssuerSerialV2`)
+- PEM and PKCS#12 key/certificate loading
+
+**Not implemented** (out of scope for this MVP): XAdES-T/-LT/-LTA (timestamps, revocation data,
+archival), CAdES/PAdES, enveloping or detached signature formats, HSM integration, and certificate
+trust/chain/revocation validation. `Xades::Bes.verify` checks that the signature is *structurally
+and cryptographically correct against the certificate embedded in the document* -- it does not
+tell you whether that certificate should be trusted.
+
+**Status**: pre-1.0, early. The test suite includes real-world interop fixtures from other
+projects (see `spec/fixtures/interop/SOURCES.md`) and a golden fixture matching KSeF's published
+`AuthTokenRequest` schema, but this gem has not yet been independently cross-checked against a
+third-party validator (`xmlsec1`, esig/dss) or a live KSeF test environment. Please verify against
+your target system before relying on it for anything regulated, and open an issue if you do.
+
+## Installation
+
+```bash
+bundle add xades
+```
+
+## Usage
+
+```ruby
+require "xades"
+
+certificate = Xades::Certificate.from_pem(
+  cert: File.read("cert.pem"),
+  key: File.read("key.pem")
+)
+# or: Xades::Certificate.from_pkcs12(File.read("cert.p12"), "password")
+
+signed_xml = Xades::Bes.sign(xml, certificate: certificate)
+
+result = Xades::Bes.verify(signed_xml)
+result.valid?  # => true
+result.errors  # => []
+```
+
+`Xades::Bes.sign` accepts:
+
+| option | default | |
+|---|---|---|
+| `certificate:` | *(required)* | an `Xades::Certificate` |
+| `signing_time:` | `Time.now.utc` | embedded as `xades:SigningTime` |
+| `signing_certificate_version:` | `:v2` | `:v2` (`SigningCertificateV2`/`IssuerSerialV2`) or `:v1` (`SigningCertificate`/`IssuerSerial`) |
+
+The certificate's key type (RSA or EC) determines the signature algorithm automatically.
+
+### KSeF example
+
+```ruby
+auth_token_request = <<~XML
+  <AuthTokenRequest xmlns="http://ksef.mf.gov.pl/auth/token/2.1">
+    <Challenge>#{challenge}</Challenge>
+    <ContextIdentifier><Nip>#{nip}</Nip></ContextIdentifier>
+    <SubjectIdentifierType>certificateSubject</SubjectIdentifierType>
+  </AuthTokenRequest>
+XML
+
+signed = Xades::Bes.sign(auth_token_request, certificate: certificate)
+# POST `signed` to /api/v2/auth/xades-signature
+```
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+```
+
+The test suite (`spec/`) combines three kinds of coverage, modeled on how other languages'
+XAdES libraries test themselves (`signxml` in Python, `xadesjs` in Node, `esig/dss` in Java --
+see `spec/fixtures/interop/SOURCES.md`):
+
+- **Unit specs** (`spec/xades/`) for each internal component
+- **Conformance specs** (`spec/conformance/`), asserting the exact BASELINE-B structural
+  requirements a signature must (and must not) satisfy, mirroring `esig/dss`'s
+  `XAdESBaselineBTest` pattern
+- **Interop specs** (`spec/interop/`), verifying real-world XAdES documents vendored from other
+  projects' test suites, plus a golden fixture built against KSeF's published `AuthTokenRequest`
+  schema and XAdES parameter constraints
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/khasinski/xades.
+
+## License
+
+The gem's own code is available as open source under the [MIT License](LICENSE.txt). Some test
+fixtures under `spec/fixtures/interop/` are vendored from other projects under their own licenses
+-- see `NOTICE` and `spec/fixtures/interop/SOURCES.md`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/xades/algorithms.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Xades
+  module Algorithms
+    DS_NAMESPACE = "http://www.w3.org/2000/09/xmldsig#"
+    XADES_NAMESPACE = "http://uri.etsi.org/01903/v1.3.2#"
+    XADES_SIGNED_PROPERTIES_TYPE = "http://uri.etsi.org/01903#SignedProperties"
+
+    C14N_EXCLUSIVE = "http://www.w3.org/2001/10/xml-exc-c14n#"
+    ENVELOPED_SIGNATURE = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
+
+    DIGEST_SHA256 = "http://www.w3.org/2001/04/xmlenc#sha256"
+
+    SIGNATURE_RSA_SHA256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+    SIGNATURE_ECDSA_SHA256 = "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"
+  end
+end

data/lib/xades/bes.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Xades
+  # Public entry point: XAdES-BES / BASELINE-B signing and verification.
+  #
+  #   certificate = Xades::Certificate.from_pem(cert: File.read("cert.pem"), key: File.read("key.pem"))
+  #   signed_xml  = Xades::Bes.sign(xml, certificate: certificate)
+  #   result      = Xades::Bes.verify(signed_xml)
+  #   result.valid? # => true
+  module Bes
+    def self.sign(xml, certificate:, signing_time: Time.now.utc, signing_certificate_version: :v2)
+      Signer.new(
+        certificate: certificate,
+        signing_time: signing_time,
+        signing_certificate_version: signing_certificate_version
+      ).sign(xml)
+    end
+
+    def self.verify(xml)
+      Verifier.verify(xml)
+    end
+  end
+end

data/lib/xades/builder/key_info.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Xades
+  module Builder
+    # Builds <ds:KeyInfo><ds:X509Data><ds:X509Certificate>.
+    module KeyInfo
+      def self.build(certificate:, id:)
+        <<~XML.strip
+          <ds:KeyInfo xmlns:ds="#{Algorithms::DS_NAMESPACE}" Id="#{id}"><ds:X509Data><ds:X509Certificate>#{certificate.base64_der}</ds:X509Certificate></ds:X509Data></ds:KeyInfo>
+        XML
+      end
+    end
+  end
+end

data/lib/xades/builder/qualifying_properties.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Xades
+  module Builder
+    # Builds the <xades:QualifyingProperties>/<xades:SignedProperties> fragment: SigningTime +
+    # SigningCertificate (V1, ds:X509IssuerName/X509SerialNumber) or V2 (xades:IssuerSerialV2, RFC 5035).
+    module QualifyingProperties
+      def self.build(certificate:, signature_id:, signed_properties_id:, signing_time:, version: :v2)
+        <<~XML.strip
+          <xades:QualifyingProperties xmlns:xades="#{Algorithms::XADES_NAMESPACE}" xmlns:ds="#{Algorithms::DS_NAMESPACE}" Target="##{signature_id}"><xades:SignedProperties Id="#{signed_properties_id}"><xades:SignedSignatureProperties><xades:SigningTime>#{format_time(signing_time)}</xades:SigningTime>#{signing_certificate(certificate, version)}</xades:SignedSignatureProperties></xades:SignedProperties></xades:QualifyingProperties>
+        XML
+      end
+
+      def self.format_time(time)
+        time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+      end
+      private_class_method :format_time
+
+      def self.signing_certificate(certificate, version)
+        case version
+        when :v2 then signing_certificate_v2(certificate)
+        when :v1 then signing_certificate_v1(certificate)
+        else raise ArgumentError, "signing_certificate_version must be :v1 or :v2, got #{version.inspect}"
+        end
+      end
+      private_class_method :signing_certificate
+
+      def self.cert_digest(certificate)
+        <<~XML.strip
+          <ds:DigestMethod Algorithm="#{Algorithms::DIGEST_SHA256}"/><ds:DigestValue>#{certificate.sha256_digest_base64}</ds:DigestValue>
+        XML
+      end
+      private_class_method :cert_digest
+
+      def self.signing_certificate_v2(certificate)
+        <<~XML.strip
+          <xades:SigningCertificateV2><xades:Cert><xades:CertDigest>#{cert_digest(certificate)}</xades:CertDigest><xades:IssuerSerialV2>#{certificate.issuer_serial_v2_base64}</xades:IssuerSerialV2></xades:Cert></xades:SigningCertificateV2>
+        XML
+      end
+      private_class_method :signing_certificate_v2
+
+      def self.signing_certificate_v1(certificate)
+        <<~XML.strip
+          <xades:SigningCertificate><xades:Cert><xades:CertDigest>#{cert_digest(certificate)}</xades:CertDigest><xades:IssuerSerial><ds:X509IssuerName>#{Util.escape_xml_text(certificate.issuer_name)}</ds:X509IssuerName><ds:X509SerialNumber>#{certificate.serial}</ds:X509SerialNumber></xades:IssuerSerial></xades:Cert></xades:SigningCertificate>
+        XML
+      end
+      private_class_method :signing_certificate_v1
+    end
+  end
+end

data/lib/xades/builder/signed_info.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Xades
+  module Builder
+    # Builds <ds:SignedInfo>: the two References required by XAdES-BASELINE-B (the enveloped
+    # document, and the SignedProperties) plus the canonicalization/signature method declarations.
+    module SignedInfo
+      def self.build(signature_method:, document_digest:, document_reference_id:, signed_properties_id:,
+                     signed_properties_digest:)
+        <<~XML.strip
+          <ds:SignedInfo xmlns:ds="#{Algorithms::DS_NAMESPACE}"><ds:CanonicalizationMethod Algorithm="#{Algorithms::C14N_EXCLUSIVE}"/><ds:SignatureMethod Algorithm="#{signature_method}"/><ds:Reference Id="#{document_reference_id}" URI=""><ds:Transforms><ds:Transform Algorithm="#{Algorithms::ENVELOPED_SIGNATURE}"/><ds:Transform Algorithm="#{Algorithms::C14N_EXCLUSIVE}"/></ds:Transforms><ds:DigestMethod Algorithm="#{Algorithms::DIGEST_SHA256}"/><ds:DigestValue>#{document_digest}</ds:DigestValue></ds:Reference><ds:Reference Type="#{Algorithms::XADES_SIGNED_PROPERTIES_TYPE}" URI="##{signed_properties_id}"><ds:Transforms><ds:Transform Algorithm="#{Algorithms::C14N_EXCLUSIVE}"/></ds:Transforms><ds:DigestMethod Algorithm="#{Algorithms::DIGEST_SHA256}"/><ds:DigestValue>#{signed_properties_digest}</ds:DigestValue></ds:Reference></ds:SignedInfo>
+        XML
+      end
+    end
+  end
+end

data/lib/xades/c14n.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Xades
+  # Wraps Nokogiri's native Exclusive XML Canonicalization (C14N 1.0, no comments),
+  # the only canonicalization method KSeF / ETSI XAdES-BASELINE-B require.
+  module C14N
+    MODE = Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0
+
+    def self.canonicalize(node)
+      node.canonicalize(MODE)
+    end
+  end
+end

data/lib/xades/certificate.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Xades
+  # Wraps an X.509 certificate together with its private key, loaded from PEM or PKCS#12.
+  class Certificate
+    attr_reader :x509, :key
+
+    def initialize(x509:, key:)
+      unless key.is_a?(OpenSSL::PKey::RSA) || key.is_a?(OpenSSL::PKey::EC)
+        raise UnsupportedKeyError,
+              "key must be an RSA or EC private key"
+      end
+
+      @x509 = x509
+      @key = key
+    end
+
+    def self.from_pem(cert:, key:, password: nil)
+      new(x509: OpenSSL::X509::Certificate.new(cert), key: OpenSSL::PKey.read(key, password))
+    end
+
+    # +pkcs12+ may be raw PKCS#12 bytes, an IO-like object, or a path to a .p12/.pfx file.
+    def self.from_pkcs12(pkcs12, password)
+      data = if pkcs12.respond_to?(:read)
+               pkcs12.read
+             elsif pkcs12.is_a?(String) && !pkcs12.include?("\x00") && File.exist?(pkcs12)
+               File.binread(pkcs12)
+             else
+               pkcs12
+             end
+      p12 = OpenSSL::PKCS12.new(data, password)
+      new(x509: p12.certificate, key: p12.key)
+    end
+
+    def rsa?
+      key.is_a?(OpenSSL::PKey::RSA)
+    end
+
+    def ec?
+      key.is_a?(OpenSSL::PKey::EC)
+    end
+
+    def base64_der
+      Base64.strict_encode64(x509.to_der)
+    end
+
+    def sha256_digest_base64
+      Xades::Digest.sha256_base64(x509.to_der)
+    end
+
+    # RFC 2253 string form of the issuer DN, as used by ds:X509IssuerName (SigningCertificate V1).
+    def issuer_name
+      x509.issuer.to_s(OpenSSL::X509::Name::RFC2253).force_encoding(Encoding::UTF_8)
+    end
+
+    def serial
+      x509.serial.to_s
+    end
+
+    # DER-encoded IssuerSerial (RFC 5035 IssuerSerial: SEQUENCE { GeneralNames, CertificateSerialNumber }),
+    # base64-encoded, as used by xades:IssuerSerialV2 (SigningCertificate V2). Verified byte-for-byte against
+    # a real DSS-generated fixture during development.
+    def issuer_serial_v2_base64
+      self.class.issuer_serial_v2_base64_for(x509)
+    end
+
+    def self.issuer_serial_v2_base64_for(x509)
+      issuer_asn1 = OpenSSL::ASN1.decode(x509.issuer.to_der)
+      general_name = OpenSSL::ASN1::ASN1Data.new([issuer_asn1], 4, :CONTEXT_SPECIFIC)
+      general_names = OpenSSL::ASN1::Sequence.new([general_name])
+      serial_asn1 = OpenSSL::ASN1::Integer.new(x509.serial)
+      issuer_serial = OpenSSL::ASN1::Sequence.new([general_names, serial_asn1])
+      Base64.strict_encode64(issuer_serial.to_der)
+    end
+  end
+end

data/lib/xades/digest.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Xades
+  # @api private
+  module Digest
+    def self.sha256_base64(bytes)
+      Base64.strict_encode64(OpenSSL::Digest::SHA256.digest(bytes))
+    end
+  end
+end

data/lib/xades/ecdsa_signature.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Xades
+  # XMLDSig (RFC 6931) requires ECDSA SignatureValue as the raw concatenation r || s, each
+  # padded to the curve's field width -- not the DER SEQUENCE{r,s} that OpenSSL produces/expects.
+  # Conversion verified against 200+ generated signatures during development (see scratchpad).
+  module EcdsaSignature
+    FIELD_BYTES = {
+      "prime256v1" => 32,
+      "secp384r1" => 48,
+      "secp521r1" => 66
+    }.freeze
+
+    def self.field_bytes_for(ec_key)
+      FIELD_BYTES.fetch(ec_key.group.curve_name) do
+        raise UnsupportedKeyError,
+              "Unsupported EC curve: #{ec_key.group.curve_name} (supported: #{FIELD_BYTES.keys.join(", ")})"
+      end
+    end
+
+    def self.der_to_raw(der, byte_len)
+      r, s = OpenSSL::ASN1.decode(der).value
+      pad(r.value, byte_len) + pad(s.value, byte_len)
+    end
+
+    def self.raw_to_der(raw, byte_len)
+      raise MalformedDocumentError, "ECDSA SignatureValue has wrong length" unless raw.bytesize == byte_len * 2
+
+      r = OpenSSL::BN.new(raw[0, byte_len], 2)
+      s = OpenSSL::BN.new(raw[byte_len, byte_len], 2)
+      OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::Integer.new(r), OpenSSL::ASN1::Integer.new(s)]).to_der
+    end
+
+    def self.pad(integer, byte_len)
+      integer.to_s(2).rjust(byte_len, "\x00")
+    end
+    private_class_method :pad
+  end
+end

data/lib/xades/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Xades
+  class Error < StandardError; end
+
+  # Raised when a key type or curve isn't supported (only RSA and EC P-256/P-384/P-521 are).
+  class UnsupportedKeyError < Error; end
+
+  # Raised when the input XML cannot be parsed or is missing an expected signature structure.
+  class MalformedDocumentError < Error; end
+end

data/lib/xades/signer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Xades
+  # Produces an XAdES-BES / BASELINE-B enveloped signature on an XML document.
+  #
+  # Build order (each step's correctness was verified empirically against Nokogiri/OpenSSL
+  # behavior and a real DSS-generated fixture before this was written -- see scratchpad notes):
+  #   1. Digest the original document (no Signature present yet == enveloped transform is a no-op).
+  #   2. Build the whole <ds:Signature> subtree as a self-contained fragment (its own xmlns:ds /
+  #      xmlns:xades declarations) with a placeholder SignedProperties digest and SignatureValue,
+  #      and graft it onto the document root.
+  #   3. Now that SignedProperties is embedded with real ancestor context, canonicalize it and
+  #      patch its real digest into the (still embedded) SignedInfo/Reference.
+  #   4. Canonicalize the now-final SignedInfo node -- that's the exact byte sequence signed.
+  class Signer
+    def initialize(certificate:, signing_time: Time.now.utc, signing_certificate_version: :v2, id_prefix: "xades")
+      @certificate = certificate
+      @signing_time = signing_time
+      @signing_certificate_version = signing_certificate_version
+      @id_prefix = id_prefix
+    end
+
+    def sign(xml)
+      doc = Nokogiri::XML(xml.to_s)
+      raise MalformedDocumentError, "document has no root element" unless doc.root
+
+      document_digest = Xades::Digest.sha256_base64(Xades::C14N.canonicalize(doc.root))
+      signature_node = doc.root.add_child(doc.fragment(build_skeleton(document_digest)))
+
+      patch_signed_properties_digest!(signature_node)
+      patch_signature_value!(signature_node)
+
+      # Nokogiri's default to_xml applies FORMAT (pretty-printing), which inserts new whitespace
+      # text nodes on reparse -- and canonicalization treats whitespace as significant, so that
+      # would silently invalidate every digest we just computed. AS_XML alone preserves exactly
+      # the tree we signed.
+      doc.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML)
+    end
+
+    private
+
+    Ids = Struct.new(:signature, :document_reference, :signed_properties, :key_info, :signature_value)
+
+    def generate_ids
+      Ids.new(*%w[signature ref signedprops keyinfo sigvalue].map { |name| Util.random_id("#{@id_prefix}-#{name}") })
+    end
+
+    # SignedProperties' real digest isn't known yet at this point (it depends on the certificate
+    # and signing time, not the placeholder digest below) -- it's patched in once this skeleton is
+    # embedded in the document, see #patch_signed_properties_digest!.
+    def build_skeleton(document_digest)
+      ids = generate_ids
+      parts = {
+        signed_info: build_signed_info(ids, document_digest),
+        key_info: Builder::KeyInfo.build(certificate: @certificate, id: ids.key_info),
+        qualifying_properties: build_qualifying_properties(ids)
+      }
+
+      assemble_signature_xml(ids, **parts)
+    end
+
+    def build_signed_info(ids, document_digest)
+      Builder::SignedInfo.build(
+        signature_method: @certificate.ec? ? Algorithms::SIGNATURE_ECDSA_SHA256 : Algorithms::SIGNATURE_RSA_SHA256,
+        document_digest: document_digest,
+        document_reference_id: ids.document_reference,
+        signed_properties_id: ids.signed_properties,
+        signed_properties_digest: ""
+      )
+    end
+
+    def build_qualifying_properties(ids)
+      Builder::QualifyingProperties.build(
+        certificate: @certificate,
+        signature_id: ids.signature,
+        signed_properties_id: ids.signed_properties,
+        signing_time: @signing_time,
+        version: @signing_certificate_version
+      )
+    end
+
+    def assemble_signature_xml(ids, signed_info:, key_info:, qualifying_properties:)
+      <<~XML.strip
+        <ds:Signature xmlns:ds="#{Algorithms::DS_NAMESPACE}" Id="#{ids.signature}">#{signed_info}<ds:SignatureValue Id="#{ids.signature_value}"></ds:SignatureValue>#{key_info}<ds:Object>#{qualifying_properties}</ds:Object></ds:Signature>
+      XML
+    end
+
+    def patch_signed_properties_digest!(signature_node)
+      signed_properties_node = signature_node.at_xpath(".//*[local-name()='SignedProperties']")
+      digest = Xades::Digest.sha256_base64(Xades::C14N.canonicalize(signed_properties_node))
+
+      digest_value_node = signature_node.at_xpath(
+        ".//*[local-name()='Reference'][@Type='#{Algorithms::XADES_SIGNED_PROPERTIES_TYPE}']/*[local-name()='DigestValue']"
+      )
+      digest_value_node.content = digest
+    end
+
+    def patch_signature_value!(signature_node)
+      signed_info_node = signature_node.at_xpath("./*[local-name()='SignedInfo']")
+      bytes_to_sign = Xades::C14N.canonicalize(signed_info_node)
+
+      signature_value_node = signature_node.at_xpath("./*[local-name()='SignatureValue']")
+      signature_value_node.content = compute_signature(bytes_to_sign)
+    end
+
+    def compute_signature(bytes)
+      digest = OpenSSL::Digest.new("SHA256")
+      if @certificate.ec?
+        der = @certificate.key.sign(digest, bytes)
+        raw = EcdsaSignature.der_to_raw(der, EcdsaSignature.field_bytes_for(@certificate.key))
+        Base64.strict_encode64(raw)
+      else
+        Base64.strict_encode64(@certificate.key.sign(digest, bytes))
+      end
+    end
+  end
+end

data/lib/xades/util.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Xades
+  # @api private
+  module Util
+    module_function
+
+    # Escapes text for use inside XML element content (not attribute values).
+    def escape_xml_text(str)
+      str.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+    end
+
+    def random_id(prefix)
+      "#{prefix}-#{SecureRandom.hex(16)}"
+    end
+  end
+end

data/lib/xades/verifier.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Xades
+  # Verifies the structural and cryptographic correctness of an XAdES-BES signature: that the
+  # document/SignedProperties digests match and that SignatureValue matches SignedInfo under the
+  # embedded certificate's public key.
+  #
+  # This does NOT validate certificate trust, chain, revocation or validity period -- that is a
+  # separate concern (deliberately out of scope for BES-level verification; see the gem's README).
+  class Verifier
+    Result = Struct.new(:valid, :errors) do
+      def valid?
+        valid
+      end
+    end
+
+    def self.verify(xml)
+      new(xml).verify
+    end
+
+    def initialize(xml)
+      @doc = Nokogiri::XML(xml.to_s)
+    end
+
+    def verify
+      errors = []
+
+      signature_node = @doc.at_xpath("//*[local-name()='Signature']")
+      return failure("no Signature element found") unless signature_node
+
+      signed_info_node = signature_node.at_xpath("./*[local-name()='SignedInfo']")
+      return failure("no SignedInfo element found") unless signed_info_node
+
+      verify_document_digest(signature_node, signed_info_node, errors)
+      verify_signed_properties_digest(signature_node, signed_info_node, errors)
+      verify_signature_value(signature_node, signed_info_node, errors)
+      verify_signing_certificate_binding(signature_node, errors)
+
+      Result.new(errors.empty?, errors)
+    end
+
+    private
+
+    def failure(message)
+      Result.new(false, [message])
+    end
+
+    def verify_document_digest(_signature_node, signed_info_node, errors)
+      reference = signed_info_node.at_xpath(".//*[local-name()='Reference'][not(@Type)]")
+      return errors << "missing document Reference in SignedInfo" unless reference
+
+      expected = reference.at_xpath("./*[local-name()='DigestValue']")&.text
+      clone = @doc.dup(1)
+      clone.at_xpath("//*[local-name()='Signature']").unlink
+      actual = Xades::Digest.sha256_base64(Xades::C14N.canonicalize(clone.root))
+
+      errors << "document digest mismatch" unless expected == actual
+    end
+
+    def verify_signed_properties_digest(signature_node, signed_info_node, errors)
+      reference = signed_info_node.at_xpath(
+        ".//*[local-name()='Reference'][@Type='#{Algorithms::XADES_SIGNED_PROPERTIES_TYPE}']"
+      )
+      return errors << "missing SignedProperties Reference in SignedInfo" unless reference
+
+      signed_properties_node = signature_node.at_xpath(".//*[local-name()='SignedProperties']")
+      return errors << "missing SignedProperties element" unless signed_properties_node
+
+      expected = reference.at_xpath("./*[local-name()='DigestValue']")&.text
+      actual = Xades::Digest.sha256_base64(Xades::C14N.canonicalize(signed_properties_node))
+
+      errors << "SignedProperties digest mismatch" unless expected == actual
+    end
+
+    KNOWN_SIGNATURE_METHODS = [Algorithms::SIGNATURE_RSA_SHA256, Algorithms::SIGNATURE_ECDSA_SHA256].freeze
+
+    def verify_signature_value(signature_node, signed_info_node, errors)
+      signature_value_node = signature_node.at_xpath("./*[local-name()='SignatureValue']")
+      cert_text = signature_node.at_xpath(".//*[local-name()='X509Certificate']")&.text
+      return errors << "missing SignatureValue or X509Certificate" unless signature_value_node && cert_text
+
+      signature_method = signed_info_node.at_xpath("./*[local-name()='SignatureMethod']")&.[]("Algorithm")
+      unless KNOWN_SIGNATURE_METHODS.include?(signature_method)
+        return errors << "unsupported SignatureMethod: #{signature_method.inspect}"
+      end
+
+      cert = OpenSSL::X509::Certificate.new(Base64.decode64(cert_text))
+      raw_signature = Base64.decode64(signature_value_node.text)
+      bytes = Xades::C14N.canonicalize(signed_info_node)
+
+      errors << "signature does not match certificate" unless signature_valid?(cert, signature_method, raw_signature,
+                                                                               bytes)
+    end
+
+    def signature_valid?(cert, signature_method, raw_signature, bytes)
+      der = to_der_signature(signature_method, raw_signature)
+      cert.public_key.verify(OpenSSL::Digest.new("SHA256"), der, bytes)
+    end
+
+    def to_der_signature(signature_method, raw_signature)
+      return raw_signature unless signature_method == Algorithms::SIGNATURE_ECDSA_SHA256
+
+      EcdsaSignature.raw_to_der(raw_signature, raw_signature.bytesize / 2)
+    end
+
+    DIGEST_ALGORITHMS = {
+      "http://www.w3.org/2001/04/xmlenc#sha256" => OpenSSL::Digest::SHA256,
+      "http://www.w3.org/2001/04/xmlenc#sha512" => OpenSSL::Digest::SHA512,
+      "http://www.w3.org/2000/09/xmldsig#sha1" => OpenSSL::Digest::SHA1
+    }.freeze
+
+    CERT_DIGEST_XPATH = ".//*[local-name()='SigningCertificate' or local-name()='SigningCertificateV2']" \
+                         "//*[local-name()='CertDigest']"
+
+    # xades:SigningCertificate(V2)/.../CertDigest is a signed *claim* about which certificate was
+    # used. It's covered by the signature (it's inside SignedProperties), so it can't be tampered
+    # with in isolation -- but nothing else stops it from simply being wrong/stale from the start
+    # (a "certificate substitution" nonconformance some real-world XAdES validators, incl. DSS,
+    # reject). We bind the claim to the certificate actually present in KeyInfo.
+    def verify_signing_certificate_binding(signature_node, errors)
+      cert_digest_node = signature_node.at_xpath(CERT_DIGEST_XPATH)
+      return unless cert_digest_node # SigningCertificate is optional at the schema level; nothing to bind
+
+      cert_text = signature_node.at_xpath(".//*[local-name()='X509Certificate']")&.text
+      return errors << "SigningCertificate present but no X509Certificate to bind it to" unless cert_text
+
+      verify_cert_digest(cert_digest_node, cert_text, errors)
+      verify_issuer_serial_v2_binding(signature_node, cert_text, errors)
+    end
+
+    def verify_cert_digest(cert_digest_node, cert_text, errors)
+      algorithm_uri = cert_digest_node.at_xpath("./*[local-name()='DigestMethod']")&.[]("Algorithm")
+      digest_class = DIGEST_ALGORITHMS[algorithm_uri]
+      return errors << "unsupported CertDigest algorithm: #{algorithm_uri.inspect}" unless digest_class
+
+      expected = cert_digest_node.at_xpath("./*[local-name()='DigestValue']")&.text
+      actual = Base64.strict_encode64(digest_class.digest(Base64.decode64(cert_text)))
+
+      errors << "SigningCertificate digest does not match the embedded certificate" unless expected == actual
+    end
+
+    # IssuerSerialV2 is DER (RFC 5035), so a byte comparison against a freshly-recomputed value is
+    # exact and implementation-independent (verified against a real DSS fixture during development).
+    # We deliberately do NOT attempt the same for the V1 xades:IssuerSerial form: it's a
+    # ds:X509IssuerName *string*, and RFC 2253 rendering differs enough across implementations
+    # (whitespace, escaping, attribute case) that comparing it byte-for-byte would produce false
+    # mismatches on legitimately-valid third-party documents.
+    def verify_issuer_serial_v2_binding(signature_node, cert_text, errors)
+      issuer_serial_v2_node = signature_node.at_xpath(".//*[local-name()='IssuerSerialV2']")
+      return unless issuer_serial_v2_node
+
+      cert = OpenSSL::X509::Certificate.new(Base64.decode64(cert_text))
+      expected = issuer_serial_v2_node.text.strip
+      actual = Xades::Certificate.issuer_serial_v2_base64_for(cert)
+
+      errors << "IssuerSerialV2 does not match the embedded certificate's issuer/serial" unless expected == actual
+    end
+  end
+end

data/lib/xades/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Xades
+  VERSION = "0.1.0"
+end

data/lib/xades.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "securerandom"
+require "nokogiri"
+
+require_relative "xades/version"
+require_relative "xades/errors"
+require_relative "xades/algorithms"
+require_relative "xades/util"
+require_relative "xades/c14n"
+require_relative "xades/digest"
+require_relative "xades/certificate"
+require_relative "xades/ecdsa_signature"
+require_relative "xades/builder/key_info"
+require_relative "xades/builder/signed_info"
+require_relative "xades/builder/qualifying_properties"
+require_relative "xades/signer"
+require_relative "xades/verifier"
+require_relative "xades/bes"

data/sig/xades.rbs

@@ -0,0 +1,4 @@
+module Xades
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: xades
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Hasinski
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: 'Sign and verify XML documents with XAdES-BES / BASELINE-B advanced electronic
+  signatures (ETSI EN 319 132), the profile used for eIDAS-adjacent flows such as
+  Poland''s KSeF e-invoicing authentication. Pure MRI: Nokogiri for XML/C14N, OpenSSL
+  for RSA/ECDSA.'
+email:
+- krzysztof.hasinski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- NOTICE
+- README.md
+- Rakefile
+- lib/xades.rb
+- lib/xades/algorithms.rb
+- lib/xades/bes.rb
+- lib/xades/builder/key_info.rb
+- lib/xades/builder/qualifying_properties.rb
+- lib/xades/builder/signed_info.rb
+- lib/xades/c14n.rb
+- lib/xades/certificate.rb
+- lib/xades/digest.rb
+- lib/xades/ecdsa_signature.rb
+- lib/xades/errors.rb
+- lib/xades/signer.rb
+- lib/xades/util.rb
+- lib/xades/verifier.rb
+- lib/xades/version.rb
+- sig/xades.rbs
+homepage: https://github.com/khasinski/xades
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/khasinski/xades
+  source_code_uri: https://github.com/khasinski/xades
+  changelog_uri: https://github.com/khasinski/xades/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: XAdES-BES/BASELINE-B XML signing and verification (ETSI EN 319 132) for pure
+  Ruby.
+test_files: []