Repository navigation
Conversation
There was a problem hiding this comment.
🟡 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
- 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
- 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
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
left a comment
There was a problem hiding this comment.
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. |

Description
This PR adds a new plugin,
xml-signer, which adds an envelopedXML 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:
reference;
APISIX has no plugin that produces XML signatures today.
What the plugin does
During the
rewritephase, for requests whose method is inrequest.methods:401unless an authentication plugin attributed itto a Consumer (
request.require_consumer, defaulttrue).Content-Typeagainstrequest.content_types, rejects anyContent-Encodingother thanidentityand any non-UTF-8charset, andreads the body up to
request.max_body_bytes.documents that are not namespace well-formed.
ds:Signature.Reference URI="")with the enveloped-signature and exclusive canonicalization transforms.
ds:SignedInfo, signs it with the configured RSA key, and addsds:KeyInfowith the X.509 certificate unlesssignature.key_infoisnone.Content-Length, and removesContent-MD5,Digest,Content-DigestandRepr-Digest, which nolonger match the body.
Requests with other methods pass through unchanged.
Configuration
credentials.certificate$secret://…,$env://…).credentials.private_keyencrypt_fields.signature.algorithmrsa-sha256rsa-sha256, orrsa-sha1for legacy verifiers.signature.key_infox509_datax509_dataembeds the certificate;noneomitsds:KeyInfo.request.methods["POST"]request.content_types["application/xml", "text/xml"]request.max_body_bytes5242880client_max_body_sizeor aclient-controllimit.request.require_consumertrueExample:
{ "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
answers
401, so anonymous clients cannot get documents signed with thegateway's key.
rsa-sha256requires an RSA key of at least 2048 bits.rsa-sha1exists only for legacy verifiers: it accepts keys of at least 1024bits and logs a warning on every signed request.
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.
parser runs with
XML_PARSE_NONETand withoutNOENT/DTDLOAD.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).
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.
a namespace declaration that is used only in content, such as the prefix in
xsi:type="ns:Type". The plugin lists such declarations in anec:InclusiveNamespacesPrefixList, so changing their binding invalidatesthe signature. Documents without such declarations are signed exactly as
without this feature.
APISIX-Runtime
set_client_max_body_size), so a chunked upload withoutContent-Lengthcannot grow without bound.cryptographic details. Client-caused rejections are logged at
warnlevel.Error responses
401unauthorizedrequest.require_consumeristrue.400empty_body400invalid_xml400already_signedds:Signature.413body_too_large415unsupported_media_typeContent-Type,Content-Encodingorcharsetis not accepted.500credential_error500signing_errorImplementation notes for reviewers
apisix/plugins/xml-signer.lua(schema and entry point) andapisix/plugins/xml-signer/:request.lua(request pipeline),signer.lua,xml.lua(libxml2 FFI bindings and parser limits),credentials.luaandalgorithms.lua.libxml2.so.2must be present at runtime. The official Debian, Ubuntu andRed Hat images include it; images built with apisix-docker's
debian-dev/Dockerfile.localdo not, as documented. Without libxml2 theplugin still loads, logs the reason once at startup, and answers signing
requests with
500 signing_error.be reloaded (plugin hot reload) and coexist with other modules that declare
the same libxml2 types.
body-transformer(1080), and beforeproxy-rewriteandproxy-mirror, solater plugins see the signed body. Any plugin that modifies the body after
xml-signerinvalidates the signature; the docs state this.(
apisix/cli/config.lua,conf/config.yaml.example,t/admin/plugins.t). Itdoes 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.
Makefileinstall target,README.md, and theEnglish and Chinese docs navigation (
docs/*/latest/config.json).Tests
t/plugin/xml-signer.t(12 tests):KeyInfo;
independently constructed canonical form;
namespace errors;
CDATA and attribute values, and 5 MB attack documents rejected in under
2 s;
InclusiveNamespaces(including that rebinding the prefix breaks thedigest).
t/plugin/xml-signer2.t(3 tests), end to end through APISIX:key-auth, and requests without a key are rejected;415/400/413handling, including chunked bodies;client_max_body_sizeis never raised;401without a Consumer, and therequire_consumer: falseopt-out.t/plugin/xml-signer3.t(5 tests):Additional verification, not part of the test suite:
RSA-SHA1/1024-bit, and tampered copies rejected;
apisix-docker's
Dockerfile.local;make lint(luacheck 1.2.0, lj-releng), eclint and markdownlint pass.Checklist