Skip to content

feat: add xml-signer plugin for enveloped XML digital signatures - #14175

Open
keremoge wants to merge 3 commits into
apache:masterfrom
keremoge:xml-signer-plugin
Open

keremoge wants to merge 3 commits into
apache:masterfrom
keremoge:xml-signer-plugin

Conversation

@keremoge

@keremoge keremoge commented Nov 9, 2026

Copy link
Copy Markdown

Description

This PR adds a new plugin, xml-signer, which adds an enveloped
XML Digital Signature to XML request
bodies before APISIX proxies them upstream.

Motivation

Many B2B, government, banking and healthcare APIs require XML payloads to be
signed with an X.509 certificate. Today, every client has to implement
XML-DSig itself and hold the signing key. With this plugin, signing moves to
the gateway:

  • the private key lives in one place: APISIX, ideally through an APISIX Secret
    reference;
  • clients send plain XML and are authenticated by an APISIX auth plugin;
  • algorithms, key rotation and policy are managed centrally.

APISIX has no plugin that produces XML signatures today.

What the plugin does

During the rewrite phase, for requests whose method is in request.methods:

  1. Rejects the request with 401 unless an authentication plugin attributed it
    to a Consumer (request.require_consumer, default true).
  2. Checks Content-Type against request.content_types, rejects any
    Content-Encoding other than identity and any non-UTF-8 charset, and
    reads the body up to request.max_body_bytes.
  3. Parses the XML with libxml2: no network access, no DTDs or entities, and no
    documents that are not namespace well-formed.
  4. Rejects documents that already contain a ds:Signature.
  5. Computes the reference digest over the whole document (Reference URI="")
    with the enveloped-signature and exclusive canonicalization transforms.
  6. Builds ds:SignedInfo, signs it with the configured RSA key, and adds
    ds:KeyInfo with the X.509 certificate unless signature.key_info is
    none.
  7. Replaces the upstream body, updates Content-Length, and removes
    Content-MD5, Digest, Content-Digest and Repr-Digest, which no
    longer match the body.

Requests with other methods pass through unchanged.

Configuration

Attribute Type Default Description
credentials.certificate string required PEM X.509 certificate or a Secret reference ($secret://…, $env://…).
credentials.private_key string required PEM RSA private key or a Secret reference. Listed in encrypt_fields.
signature.algorithm string rsa-sha256 rsa-sha256, or rsa-sha1 for legacy verifiers.
signature.key_info string x509_data x509_data embeds the certificate; none omits ds:KeyInfo.
request.methods array ["POST"] Methods to sign.
request.content_types array ["application/xml", "text/xml"] Accepted media types.
request.max_body_bytes integer 5242880 1024 to 67108864. Never raises the operator's client_max_body_size or a client-control limit.
request.require_consumer boolean true Sign only requests attributed to a Consumer.

Example:

{
  "uri": "/signed-xml",
  "plugins": {
    "key-auth": {},
    "xml-signer": {
      "credentials": {
        "certificate": "$secret://vault/signing/xml/certificate",
        "private_key": "$secret://vault/signing/xml/private-key"
      }
    }
  },
  "upstream": {"type": "roundrobin", "nodes": {"127.0.0.1:9001": 1}}
}

Security design

  • No signing oracle by default: without an authenticated Consumer the plugin
    answers 401, so anonymous clients cannot get documents signed with the
    gateway's key.
  • Key strength: rsa-sha256 requires an RSA key of at least 2048 bits.
    rsa-sha1 exists only for legacy verifiers: it accepts keys of at least 1024
    bits and logs a warning on every signed request.
  • Credentials: they must be a matching RSA certificate and key pair, are
    parsed once and cached per worker (keyed by a SHA-256 fingerprint, so a
    rotated Secret takes effect without a reload), and a warning is logged if
    the certificate is expired or not yet valid.
  • XXE and entity expansion: documents with a DTD are rejected, and the
    parser runs with XML_PARSE_NONET and without NOENT/DTDLOAD.
  • Parser DoS: libxml2 2.9 (shipped in the Debian bookworm based images)
    parses some inputs super-linearly. A 5 MB document could keep a worker busy
    for over 13 seconds with namespace declarations, and for minutes with
    attributes. Before parsing, the plugin rejects documents in which one element
    has more than 256 attributes, or more than 128 namespace declarations are in
    scope at once. The check is linear and was differentially fuzzed against
    libxml2's own parse tree (57,000+ random documents, no undercounts).
  • Namespace well-formedness: recoverable libxml2 errors, such as an
    undeclared prefix, cause rejection, so the plugin never signs XML that
    namespace-aware verifiers would read differently. The error handler is
    created once per module load (LuaJIT has a fixed number of FFI callback
    slots), and the parser call is excluded from JIT compilation.
  • Prefixes used only in content: exclusive canonicalization does not cover
    a namespace declaration that is used only in content, such as the prefix in
    xsi:type="ns:Type". The plugin lists such declarations in an
    ec:InclusiveNamespaces PrefixList, so changing their binding invalidates
    the signature. Documents without such declarations are signed exactly as
    without this feature.
  • Body size: the limit is enforced while NGINX reads the body (via
    APISIX-Runtime set_client_max_body_size), so a chunked upload without
    Content-Length cannot grow without bound.
  • Errors: responses contain only an error code, never request content or
    cryptographic details. Client-caused rejections are logged at warn level.

Error responses

Status Message Cause
401 unauthorized No authenticated Consumer while request.require_consumer is true.
400 empty_body The request has no body.
400 invalid_xml Parse failure, a namespace error, no root element, a DTD, or the parser limits are exceeded.
400 already_signed The document already contains a ds:Signature.
413 body_too_large The body exceeds the effective size limit.
415 unsupported_media_type Content-Type, Content-Encoding or charset is not accepted.
500 credential_error A Secret could not be resolved, PEM parsing failed, the key is not RSA or too short, or the certificate and key do not match.
500 signing_error libxml2 is not available, or canonicalization, signing or serialization failed.

Implementation notes for reviewers

  • Files: apisix/plugins/xml-signer.lua (schema and entry point) and
    apisix/plugins/xml-signer/: request.lua (request pipeline), signer.lua,
    xml.lua (libxml2 FFI bindings and parser limits), credentials.lua and
    algorithms.lua.
  • libxml2: used through LuaJIT FFI; no new LuaRocks dependency is added.
    libxml2.so.2 must be present at runtime. The official Debian, Ubuntu and
    Red Hat images include it; images built with apisix-docker's
    debian-dev/Dockerfile.local do not, as documented. Without libxml2 the
    plugin still loads, logs the reason once at startup, and answers signing
    requests with 500 signing_error.
  • FFI type definitions: struct definitions are guarded, so the module can
    be reloaded (plugin hot reload) and coexist with other modules that declare
    the same libxml2 types.
  • Priority 1026: runs after the authentication plugins and after
    body-transformer (1080), and before proxy-rewrite and proxy-mirror, so
    later plugins see the signed body. Any plugin that modifies the body after
    xml-signer invalidates the signature; the docs state this.
  • Plugin list: the plugin is added to the default plugin list
    (apisix/cli/config.lua, conf/config.yaml.example, t/admin/plugins.t). It
    does nothing unless configured on a Route, but on hosts without libxml2 it
    logs the startup error described above. I'm happy to remove it from the
    default list if maintainers prefer.
  • Also changed: the Makefile install target, README.md, and the
    English and Chinese docs navigation (docs/*/latest/config.json).

Tests

  • t/plugin/xml-signer.t (12 tests):
    • schema validation;
    • signing and independent verification for RSA-SHA256, RSA-SHA1 and no
      KeyInfo;
    • namespace conflicts and processing instructions, verified against an
      independently constructed canonical form;
    • rejection of DTD/XXE, already signed documents, non-RSA keys, and
      namespace errors;
    • minimum key sizes per algorithm;
    • parser limits at their exact boundaries, including decoys in comments,
      CDATA and attribute values, and 5 MB attack documents rejected in under
      2 s;
    • the certificate validity warning;
    • InclusiveNamespaces (including that rebinding the prefix breaks the
      digest).
  • t/plugin/xml-signer2.t (3 tests), end to end through APISIX:
    • signing behind key-auth, and requests without a key are rejected;
    • pass-through of other methods;
    • 415/400/413 handling, including chunked bodies;
    • the operator client_max_body_size is never raised;
    • 401 without a Consumer, and the require_consumer: false opt-out.
  • t/plugin/xml-signer3.t (5 tests):
    • the request pipeline with more than 100 headers;
    • module reload and the credential cache;
    • normalization of defaults;
    • behavior without libxml2;
    • the Consumer check.

Additional verification, not part of the test suite:

  • signatures verified with xmlsec1 1.2.39 for RSA-SHA256/2048-bit and
    RSA-SHA1/1024-bit, and tampered copies rejected;
  • the plugin tested in an APISIX 3.19.0 image built from source with
    apisix-docker's Dockerfile.local;
  • make lint (luacheck 1.2.0, lj-releng), eclint and markdownlint pass.

Checklist

  • I have explained the need for this PR and the problem it solves
  • I have explained the changes or the new features added to this PR
  • I have added tests corresponding to this change
  • I have updated the documentation to reflect this change
  • I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first)

Copilot AI balanced review requested due to automatic review settings November 9, 2026 09:02

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical parser-limit bypasses and quadratic scanning can block workers, while namespace-handling flaws can invalidate signatures or let content tampering go undetected.

4 open issues
What changed in this PR

Adds xml-signer to APISIX so the gateway can sign XML request bodies before forwarding them upstream, centralizing signing credentials and policy.

Changes:

  • Implements enveloped XML signatures with RSA-SHA256, legacy RSA-SHA1, and optional embedded certificates.
  • Adds Consumer checks, request validation, parser limits, and credential caching.
  • Integrates installation, default plugin registration, bilingual documentation, and tests.
File Description
t/​plugin/​xml-signer3.t Tests request handling, reloads, caching, defaults, and missing-library behavior.
t/​plugin/​xml-signer2.t Tests proxy integration, authentication, and body-size limits.
t/​plugin/​xml-signer.t Tests signatures, credentials, namespaces, and parser limits.
t/​admin/​plugins.t Updates the expected plugin list.
README.md Links to the XML signing feature.
Makefile Installs signing helper modules.
docs/​zh/​latest/​plugins/​xml-signer.md Adds Chinese configuration and usage documentation.
docs/​zh/​latest/​config.json Adds Chinese documentation navigation.
docs/​en/​latest/​plugins/​xml-signer.md Adds English configuration and usage documentation.
docs/​en/​latest/​config.json Adds English documentation navigation.
conf/​config.yaml.example Lists the plugin and its priority.
apisix/​plugins/​xml-signer/​xml.lua Implements libxml2 bindings, parsing guards, and canonicalization.
apisix/​plugins/​xml-signer/​signer.lua Constructs and signs enveloped XML signatures.
apisix/​plugins/​xml-signer/​request.lua Validates requests and replaces bodies and related headers.
apisix/​plugins/​xml-signer/​credentials.lua Validates and caches certificate/key pairs.
apisix/​plugins/​xml-signer/​algorithms.lua Defines supported algorithms and digest generation.
apisix/​plugins/​xml-signer.lua Defines the schema, defaults, priority, and entry point.
apisix/​cli/​config.lua Registers the plugin in the default list.

Review effort: Balanced

Comment thread apisix/plugins/xml-signer/signer.lua Resolved
Comment thread apisix/plugins/xml-signer/xml.lua Resolved
Comment thread apisix/plugins/xml-signer/xml.lua Resolved
Comment thread apisix/plugins/xml-signer/xml.lua Resolved
keremoge pushed a commit to keremoge/apisix that referenced this pull request Nov 9, 2026
- Reject non-UTF-8 documents before the limit checks. libxml2 detects
  UTF-16, UTF-32 and EBCDIC from the first bytes and honors the encoding
  declaration, so a UTF-16 document hid its markup from the byte-based
  attribute and namespace limits and reached the quadratic parser paths.
  Bodies with NUL bytes, or that do not start with "<" after an optional
  UTF-8 BOM and whitespace, are rejected, and XML_PARSE_IGNORE_ENC makes
  the parser ignore the encoding declaration (UTF-7, ISO-8859-1). An
  explicit "UTF-8" encoding is not used because it limits input to about
  10 MB.
- Protect prefixes referenced in content. The PrefixList now holds the
  declared prefixes that text or attribute values refer to as
  prefix:name, including prefixes that names also use: inserting a new
  declaration on an intermediate element could otherwise change the
  meaning of xsi:type="ns:T" without changing the digest. Declarations
  that nothing refers to are no longer listed.
- Bound the PrefixList to 8 prefixes. libxml2 looks up every listed
  prefix for every canonicalized element; listing 127 unused declarations
  made canonicalizing 5 MB take about a minute. Documents that refer to
  more declared prefixes in content are rejected with invalid_xml.
- Declare the InclusiveNamespaces prefix with ensure_namespace instead of
  always "ec": when the document bound "ec" to the XML-DSig namespace, the
  signature reused it and the new declaration moved the Transform element
  into the exc-c14n namespace.
- Add tests and update the documentation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JcSc6a71nxXjd67tcV4Ye8
keremoge pushed a commit to keremoge/apisix that referenced this pull request Nov 9, 2026
- Reject non-UTF-8 messages before the limit checks. libxml2 detects
  UTF-16, UTF-32 and EBCDIC from the first bytes and honors the encoding
  declaration, so a UTF-16 message hid its markup from the byte-based
  attribute and namespace limits and reached the quadratic parser paths.
  Bodies with NUL bytes, or that do not start with "<" after an optional
  UTF-8 BOM and whitespace, are rejected, and XML_PARSE_IGNORE_ENC makes
  the parser ignore the encoding declaration (UTF-7, ISO-8859-1). An
  explicit "UTF-8" encoding is not used because it limits input to about
  10 MB.
- Protect prefixes referenced in Body content. The Body reference's
  PrefixList now holds the declared prefixes that text or attribute
  values refer to as prefix:name, including prefixes that names also
  use: inserting a new declaration on an intermediate element could
  otherwise change the meaning of xsi:type="ns:T" without changing the
  digest. Declarations that nothing refers to are no longer listed.
- Bound the PrefixList to 8 prefixes. libxml2 looks up every listed
  prefix for every canonicalized element, so a long list made
  canonicalization take up to a minute for 5 MB. Messages that refer to
  more declared prefixes in Body content are rejected with invalid_soap.
- Declare the InclusiveNamespaces prefix with ensure_namespace instead of
  always "ec": when the message bound "ec" to the XML-DSig namespace, the
  signature reused it and the new declaration moved the Transform element
  into the exc-c14n namespace. Reported for xml-signer in
  apache#14175; soap-signer had the same code.
- Add tests and update the documentation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JcSc6a71nxXjd67tcV4Ye8
keremoge pushed a commit to keremoge/apisix that referenced this pull request Nov 9, 2026
Cover the two scenarios from the review of apache#14175 exactly:

- rebinding a prefix on the element whose xsi:type refers to it, while
  a sibling element name also uses the prefix, must change the digest;
- a UTF-16 document with 1,024 namespace declarations in scope must be
  rejected before the parser, the namespace counterpart of the UTF-16
  attribute case.

Both fail on the code before 6cbb359.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JcSc6a71nxXjd67tcV4Ye8
- Bound the attribute pre-check search to its segment. count_plain
  searched to the end of the document whenever a segment had no "=",
  which made the check quadratic: 32 MB of plain text took about 17 s.
- Reject non-UTF-8 documents before the byte-based limit checks.
  libxml2 auto-detects UTF-16, whose NUL-separated attributes and xmlns
  tokens the scanners missed. Bodies with NUL bytes, or that do not
  start with "<" after an optional UTF-8 BOM, are rejected, and the
  encoding declaration is ignored (XML_PARSE_IGNORE_ENC).
- Include content prefixes in the exclusive canonicalization PrefixList.
  The list now holds the declared prefixes that text or attribute values
  refer to, even when element names also use them, so rebinding a prefix
  on the element that refers to it changes the digest. The list is
  capped at 8 prefixes, because libxml2 checks every listed prefix on
  every element.
- Avoid XMLDSig namespace prefix collisions on transforms: declare the
  InclusiveNamespaces prefix with ensure_namespace, so a document that
  binds "ec" to the XML-DSig namespace keeps the Transform element in
  that namespace.
- Add regression tests for each case, including the mixed-use rebinding
  and UTF-16 cases for both limits, and update the documentation.

@kayx23 kayx23 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentation review only; no approval or change request. The Chinese page omits two operational requirements that are present in English: (1) the complete Use Environment Variables credential workflow ($env://, Kubernetes Secret injection, nginx_config.envs, and Pod restart behavior), and (2) the requirement that APISIX-Runtime support enforcement of request.max_body_bytes while NGINX reads the body. Please add both so the English and Chinese pages expose the same credential and body-limit contract.

@keremoge

Copy link
Copy Markdown
Author

Documentation review only; no approval or change request. The Chinese page omits two operational requirements that are present in English: (1) the complete Use Environment Variables credential workflow ($env://, Kubernetes Secret injection, nginx_config.envs, and Pod restart behavior), and (2) the requirement that APISIX-Runtime support enforcement of request.max_body_bytes while NGINX reads the body. Please add both so the English and Chinese pages expose the same credential and body-limit contract.

Thanks for catching this. Updated the Chinese page with the complete environment-variable credential workflow ($env://, Kubernetes Secret injection, nginx_config.envs, and Pod restart behavior) and the APISIX-Runtime requirement to enforce request.max_body_bytes while NGINX reads the request body. Both now match the English page.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants