wssec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c4a7b1e50edb5cee54acd6da327061e37157d123eefb01e465df5922c7fb5ce
+  data.tar.gz: c7ba0c1a415432333ba763e695bc6cb050387b4a10c0442f0e14b94da6c1c20d
+SHA512:
+  metadata.gz: d443792ce61740d16058a7e0e75083f3743a54492a2ff4f11726fd138365f410a66671a70db673041ca5d4d8c86be8bba4b959292745cb29feaebc544020b79c
+  data.tar.gz: 35b2ba499928e04affbbf061a855989de044a754a5c132af1050f231f8efc1ab0d0144e3b85fae8cf5ebcba7d7708cfd8708e27a7af8059a66ee69e7e72e4b5a

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-01
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"wssec" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["bugloper@hey.com"](mailto:"bugloper@hey.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 bugloper
+
+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/README.md

@@ -0,0 +1,87 @@
+# Wssec
+
+`Wssec::Signer` adds an OASIS **WS-Security** header with a detached **XML-DSig**
+signature to a SOAP envelope — signing the `soapenv:Body` and a `wsu:Timestamp`
+with **RSA-SHA256** over **exclusive-C14N**, exactly as WSS4J-based gateways verify.
+
+It is deliberately **vendor-agnostic**: the signing key/cert, the token identifier,
+the exclusive-C14N inclusive prefix list, and the timestamp TTL are all supplied by
+the caller. The gem carries no keystore/ENV assumptions and no gateway-specific values.
+
+## Installation
+
+Path/git dependency (this gem is not published to a public registry):
+
+```ruby
+# Gemfile
+gem "wssec", path: "../../gems/wssec"
+# or
+gem "wssec", git: "https://github.com/SELISEdigitalplatforms/wssec.git"
+```
+
+## Usage
+
+```ruby
+require "wssec"
+
+key  = OpenSSL::PKey::RSA.new(File.read("private_key.pem"))   # your signing key
+cert = OpenSSL::X509::Certificate.new(File.read("cert.pem"))  # embedded as the BinarySecurityToken
+
+signer = Wssec::Signer.new(
+  key:                key,
+  cert:               cert,
+  key_identifier:     "my-key",           # BST wsu:Id becomes "X509-my-key"
+  inclusive_prefixes: %w[wsse wsu soapenv ds], # exclusive-C14N PrefixList (gateway-specific)
+  timestamp_ttl:      300                 # seconds until the Timestamp expires (optional)
+)
+
+doc = Nokogiri::XML(soap_envelope_string)
+signer.sign!(doc, body_id: "Id-#{SecureRandom.hex(16)}")
+signed_xml = doc.to_xml
+```
+
+`sign!` mutates the passed Nokogiri document in place and returns it. Pass `now:` to
+pin the timestamp (useful for deterministic tests).
+
+### Notes
+
+- `inclusive_prefixes` is **required** — supply the exact prefix list your gateway
+  expects rendered into each signed subtree. There is no default, to avoid baking in
+  any single vendor's assumptions.
+- The digest references use exclusive-C14N **with** the prefix list; `SignedInfo` is
+  canonicalized **without** one. This matches how WSS4J recomputes and verifies, so
+  the signing internals are byte-sensitive — treat them as such.
+
+## Alternatives
+
+Before reaching for this gem, check whether an existing library fits — it may save
+you from owning XML-DSig correctness yourself:
+
+- **[akami](https://github.com/savonrb/akami)** (1.3.1) — the closest match: builds a
+  `wsse:Security` header with Timestamp and X.509 signature (`Akami::WSSE::Signature` /
+  `Akami::WSSE::VerifySignature`), part of the Savon SOAP ecosystem. Choose it for a
+  batteries-included WSSE layer when you don't need byte-level control over
+  canonicalization or the exclusive-C14N inclusive-prefix list.
+- **[xmldsig](https://github.com/benoist/xmldsig)** (0.7.0) — a general XML-DSig
+  sign/verify implementation. Not WS-Security aware: you assemble the `wsse:Security` /
+  `BinarySecurityToken` / `SecurityTokenReference` scaffolding yourself. Pairs with
+  **[nokogiri-signatures](https://github.com/jch/nokogiri-signatures)** for a
+  Nokogiri-friendly interface.
+- **xmlsec** (libxmlsec1 native bindings) — the most standards-complete option, at the
+  cost of a C system dependency.
+
+**Why this gem exists:** it targets gateways (e.g. Apache WSS4J) that re-verify the exact
+canonical bytes. It gives the caller precise control over the inclusive-prefix list and
+the detached Body + Timestamp references, and deliberately canonicalizes `SignedInfo`
+*without* a prefix list to match how those gateways verify. If you don't need that
+byte-level fidelity, akami or xmldsig will likely serve you with less code to maintain.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then `rake test`
+to run the tests (minitest) or `rake` for tests + RuboCop. `bin/console` gives an
+interactive prompt.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/generators/wssec/install/install_generator.rb

@@ -0,0 +1,17 @@
+require "rails/generators/base"
+
+module Wssec
+  module Generators
+    # `rails g wssec:install` — writes config/initializers/wssec.rb pre-populated
+    # with every Wssec default so they can be reviewed and overridden in place.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Wssec initializer (config/initializers/wssec.rb) with the default configuration."
+
+      def copy_initializer
+        template "wssec.rb", "config/initializers/wssec.rb"
+      end
+    end
+  end
+end

data/lib/generators/wssec/install/templates/wssec.rb

@@ -0,0 +1,28 @@
+# Wssec configuration. Every value below is the built-in default — edit any of
+# them to match your SOAP gateway's WS-Security expectations, or delete the ones
+# you don't need to override (the gem falls back to the same defaults).
+#
+# Note: `inclusive_prefixes` (the exclusive-C14N PrefixList) and the signing
+# key/cert are gateway-specific and passed per call to Wssec::Signer.new — they
+# are intentionally not configured here.
+Wssec.configure do |config|
+  # OASIS / SOAP / XML-DSig namespace URIs bound to the wsse/wsu/soapenv/ds prefixes.
+  config.namespaces = {
+    wsse: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
+    wsu: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd",
+    soapenv: "http://schemas.xmlsoap.org/soap/envelope/",
+    ds: "http://www.w3.org/2000/09/xmldsig#"
+  }
+
+  # Canonicalization / signature / digest algorithm identifiers (declared in the XML).
+  config.exc_c14n         = "http://www.w3.org/2001/10/xml-exc-c14n#"
+  config.signature_method = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+  config.digest_method    = "http://www.w3.org/2001/04/xmlenc#sha256"
+
+  # WS-Security token encoding / value types for the BinarySecurityToken.
+  config.encoding_type = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
+  config.value_type    = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
+
+  # Seconds until the wsu:Timestamp expires.
+  config.timestamp_ttl = 300
+end

data/lib/wssec/configuration.rb

@@ -0,0 +1,34 @@
+module Wssec
+  # Holds the protocol-level defaults a WS-Security signature is built from:
+  # namespace URIs, algorithm identifiers, token types and the timestamp TTL.
+  # Every value ships with a standards-compliant default and can be overridden
+  # globally via `Wssec.configure` (see `rails g wssec:install`) or per-signer.
+  class Configuration
+    DEFAULT_NAMESPACES = {
+      wsse: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
+      wsu: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd",
+      soapenv: "http://schemas.xmlsoap.org/soap/envelope/",
+      ds: "http://www.w3.org/2000/09/xmldsig#"
+    }.freeze
+
+    DEFAULT_EXC_C14N         = "http://www.w3.org/2001/10/xml-exc-c14n#"
+    DEFAULT_SIGNATURE_METHOD = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+    DEFAULT_DIGEST_METHOD    = "http://www.w3.org/2001/04/xmlenc#sha256"
+    DEFAULT_ENCODING_TYPE    = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
+    DEFAULT_VALUE_TYPE       = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
+    DEFAULT_TIMESTAMP_TTL    = 300 # seconds
+
+    attr_accessor :namespaces, :exc_c14n, :signature_method, :digest_method,
+                  :encoding_type, :value_type, :timestamp_ttl
+
+    def initialize
+      @namespaces       = DEFAULT_NAMESPACES.dup
+      @exc_c14n         = DEFAULT_EXC_C14N
+      @signature_method = DEFAULT_SIGNATURE_METHOD
+      @digest_method    = DEFAULT_DIGEST_METHOD
+      @encoding_type    = DEFAULT_ENCODING_TYPE
+      @value_type       = DEFAULT_VALUE_TYPE
+      @timestamp_ttl    = DEFAULT_TIMESTAMP_TTL
+    end
+  end
+end

data/lib/wssec/signer.rb

@@ -0,0 +1,162 @@
+require "nokogiri"
+require "openssl"
+require "base64"
+
+module Wssec
+  # Signs a SOAP envelope with an OASIS WS-Security header carrying a detached
+  # XML-DSig signature (RSA-SHA256 / SHA256, exclusive-C14N) over the Body and a
+  # Timestamp, exactly as a WSS4J-based gateway expects.
+  #
+  #   doc = Nokogiri::XML(soap_envelope)
+  #   Wssec::Signer.new(
+  #     key: rsa_key, cert: x509_cert, key_identifier: "my-key",
+  #     inclusive_prefixes: %w[wsse wsu soapenv ds]
+  #   ).sign!(doc, body_id: "Id-#{SecureRandom.hex(16)}")
+  #   doc.to_xml
+  #
+  # The signer is vendor-agnostic: key/cert, the token identifier and the C14N
+  # inclusive prefix list are supplied per call, while namespaces, algorithm
+  # identifiers, token types and the timestamp TTL come from +config+ (defaults
+  # to the global Wssec.configuration).
+  class Signer # rubocop:disable Metrics/ClassLength
+    # key  -- OpenSSL::PKey::RSA private key used to sign.
+    # cert -- OpenSSL::X509::Certificate embedded as the BinarySecurityToken.
+    # key_identifier -- names the token (BST wsu:Id becomes "X509-#{key_identifier}").
+    # inclusive_prefixes -- namespace prefixes rendered into each signed subtree
+    #   (the exclusive-C14N PrefixList); gateway-specific, so the caller supplies it.
+    # timestamp_ttl -- seconds until the wsu:Timestamp expires (defaults to config).
+    # config -- Wssec::Configuration for namespaces/algorithms/token types.
+    def initialize(key:, cert:, key_identifier:, inclusive_prefixes:, timestamp_ttl: nil, config: Wssec.configuration)
+      @key                = key
+      @cert               = cert
+      @key_identifier     = key_identifier
+      @inclusive_prefixes = inclusive_prefixes
+      @config             = config
+      @timestamp_ttl      = timestamp_ttl || config.timestamp_ttl
+    end
+
+    # Adds the signed <wsse:Security> header to +document+ (a Nokogiri doc) in place.
+    def sign!(document, body_id:, now: Time.now.utc)
+      root   = document.root
+      header = root.at_xpath("soapenv:Header", "soapenv" => ns[:soapenv]) ||
+               root.prepend_child(Nokogiri::XML::Node.new("soapenv:Header", document))
+      body   = root.at_xpath("soapenv:Body", "soapenv" => ns[:soapenv])
+      raise Wssec::Error, "envelope has no soapenv:Body" unless body
+
+      tag_body(body, body_id)
+      security = build_security_header(document, header, now)
+      append_binary_security_token(document, security)
+      append_signature(document, security, body, body_id)
+      document
+    end
+
+    private
+
+    def ns
+      @config.namespaces
+    end
+
+    def tag_body(body, body_id)
+      ensure_ns(body, "wsu", ns[:wsu])
+      body["wsu:Id"] = body_id
+    end
+
+    def build_security_header(document, header, now)
+      security = Nokogiri::XML::Node.new("wsse:Security", document)
+      security.add_namespace_definition("wsse", ns[:wsse])
+      security.add_namespace_definition("wsu", ns[:wsu])
+      security.add_namespace_definition("ds", ns[:ds])
+      security["soapenv:mustUnderstand"] = "1"
+      header.add_child(security)
+
+      timestamp = security.add_child(Nokogiri::XML::Node.new("wsu:Timestamp", document))
+      timestamp["wsu:Id"] = "TS-1"
+      timestamp.add_child(Nokogiri::XML::Node.new("wsu:Created", document)).content = format_time(now)
+      timestamp.add_child(Nokogiri::XML::Node.new("wsu:Expires", document)).content = format_time(now + @timestamp_ttl)
+      security
+    end
+
+    def append_binary_security_token(document, security)
+      bst = security.add_child(Nokogiri::XML::Node.new("wsse:BinarySecurityToken", document))
+      bst["EncodingType"] = @config.encoding_type
+      bst["ValueType"]    = @config.value_type
+      bst["wsu:Id"]       = bst_id
+      bst.content         = Base64.strict_encode64(@cert.to_der)
+    end
+
+    def append_signature(document, security, body, body_id)
+      timestamp = security.at_xpath("wsu:Timestamp", "wsu" => ns[:wsu])
+
+      signature = Nokogiri::XML::Node.new("ds:Signature", document)
+      signature.add_namespace_definition("ds", ns[:ds])
+      signed_info = signature.add_child(Nokogiri::XML::Node.new("ds:SignedInfo", document))
+      add_attr(signed_info.add_child(Nokogiri::XML::Node.new("ds:CanonicalizationMethod", document)), "Algorithm", @config.exc_c14n)
+      add_attr(signed_info.add_child(Nokogiri::XML::Node.new("ds:SignatureMethod", document)), "Algorithm", @config.signature_method)
+      add_reference(document, signed_info, "##{body_id}", digest(body))
+      add_reference(document, signed_info, "#TS-1", digest(timestamp))
+
+      signature_value = signature.add_child(Nokogiri::XML::Node.new("ds:SignatureValue", document))
+      append_key_info(document, signature)
+
+      # Attach the signature into its FINAL position BEFORE canonicalizing SignedInfo:
+      # exclusive-C14N must see the namespace context SignedInfo will have on the wire,
+      # otherwise the gateway recomputes different bytes and rejects with FAILED_AUTHENTICATION.
+      security.add_child(signature)
+      signed_info_c14n = canonicalize(signed_info, nil)
+      signature_value.content = Base64.strict_encode64(@key.sign(OpenSSL::Digest.new("SHA256"), signed_info_c14n))
+    end
+
+    def append_key_info(document, signature)
+      key_info = signature.add_child(Nokogiri::XML::Node.new("ds:KeyInfo", document))
+      str = key_info.add_child(Nokogiri::XML::Node.new("wsse:SecurityTokenReference", document))
+      str.add_namespace_definition("wsse", ns[:wsse])
+      reference = str.add_child(Nokogiri::XML::Node.new("wsse:Reference", document))
+      reference["URI"]       = "##{bst_id}"
+      reference["ValueType"] = @config.value_type
+    end
+
+    def add_reference(document, signed_info, uri, digest_value)
+      reference = signed_info.add_child(Nokogiri::XML::Node.new("ds:Reference", document))
+      reference["URI"] = uri
+      transform = reference
+                  .add_child(Nokogiri::XML::Node.new("ds:Transforms", document))
+                  .add_child(Nokogiri::XML::Node.new("ds:Transform", document))
+      transform["Algorithm"] = @config.exc_c14n
+      inclusive = transform.add_child(Nokogiri::XML::Node.new("ec:InclusiveNamespaces", document))
+      inclusive.add_namespace_definition("ec", @config.exc_c14n)
+      inclusive["PrefixList"] = @inclusive_prefixes.join(" ")
+      add_attr(reference.add_child(Nokogiri::XML::Node.new("ds:DigestMethod", document)), "Algorithm", @config.digest_method)
+      reference.add_child(Nokogiri::XML::Node.new("ds:DigestValue", document)).content = digest_value
+    end
+
+    # Reference digests use exclusive-C14N WITH the inclusive prefix list.
+    def digest(element)
+      Base64.strict_encode64(OpenSSL::Digest::SHA256.digest(canonicalize(element, @inclusive_prefixes)))
+    end
+
+    # SignedInfo is canonicalized WITHOUT a prefix list. The old bridge documented this
+    # as a signxml 2.8 workaround; the gateway verifies the same way, so keep it.
+    def canonicalize(element, inclusive_prefixes)
+      element.canonicalize(Nokogiri::XML::XML_C14N_EXCLUSIVE_1_0, inclusive_prefixes)
+    end
+
+    def bst_id
+      "X509-#{@key_identifier}"
+    end
+
+    def format_time(time)
+      time.strftime("%Y-%m-%dT%H:%M:%SZ")
+    end
+
+    def add_attr(node, name, value)
+      node[name] = value
+      node
+    end
+
+    def ensure_ns(node, prefix, href)
+      return if node.namespace_definitions.any? { |definition| definition.prefix == prefix }
+
+      node.add_namespace_definition(prefix, href)
+    end
+  end
+end

data/lib/wssec/version.rb

@@ -0,0 +1,3 @@
+module Wssec
+  VERSION = "0.1.0"
+end

data/lib/wssec.rb

@@ -0,0 +1,28 @@
+require_relative "wssec/version"
+require_relative "wssec/configuration"
+
+# OASIS WS-Security detached XML-DSig signing for SOAP envelopes. See Wssec::Signer
+# for the signer and Wssec::Configuration for the tunable protocol defaults.
+module Wssec
+  class Error < StandardError; end
+
+  class << self
+    # Global configuration (namespaces, algorithms, token types, timestamp TTL).
+    # Signers read from this unless given their own +config:+.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Wssec.configure { |config| config.timestamp_ttl = 600 }
+    def configure
+      yield(configuration)
+    end
+
+    # Restore all defaults — primarily for test isolation.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require_relative "wssec/signer"

data/sig/wssec.rbs

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

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: wssec
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- bugloper
+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.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.13'
+description: 'Signs a SOAP envelope''s Body and Timestamp with a WS-Security header
+  carrying a detached XML-DSig signature (RSA-SHA256, exclusive-C14N), as expected
+  by WSS4J-based gateways. Vendor-agnostic: key, cert, token id, C14N prefix list
+  and timestamp TTL are all supplied by the caller.'
+email:
+- bugloper@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/wssec/install/install_generator.rb
+- lib/generators/wssec/install/templates/wssec.rb
+- lib/wssec.rb
+- lib/wssec/configuration.rb
+- lib/wssec/signer.rb
+- lib/wssec/version.rb
+- sig/wssec.rbs
+homepage: https://github.com/SELISEdigitalplatforms/wssec
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/SELISEdigitalplatforms/wssec
+  source_code_uri: https://github.com/SELISEdigitalplatforms/wssec
+  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.3
+specification_version: 4
+summary: OASIS WS-Security detached XML-DSig signer for SOAP envelopes.
+test_files: []