signxml

Warnings

• breaking Version 4.0.0 introduced a major infrastructure change, replacing PyOpenSSL with Cryptography for core certificate and key handling. The `ca_path` parameter for specifying CA certificate stores was removed and replaced by `ca_pem_file`.
  Fix: Update your code to use `cryptography` types and `ca_pem_file` where applicable. Review API documentation for updated methods, especially for certificate chain validation.
• breaking Version 4.0.4 contained critical security fixes addressing HMAC algorithm confusion and timing attacks. Running older versions with HMAC-based signatures is highly insecure.
  Fix: Upgrade to signxml version 4.0.4 or newer immediately to mitigate these vulnerabilities.
• breaking As of version 4.4.0, DTD (Document Type Declaration) declarations are forbidden in XML input for enhanced security, preventing XML External Entity (XXE) attacks.
  Fix: Ensure your XML inputs do not contain DTD declarations. If you are processing external XML, sanitize or transform it to remove DTDs before passing it to signxml.
• gotcha signxml relies heavily on `lxml.etree` for its advanced XML parsing, canonicalization, and security features. Using Python's standard `xml.etree.ElementTree` can lead to inconsistent behavior, especially with namespace handling, and may bypass lxml's security protections.
  Fix: Always import `etree` from `lxml` (`from lxml import etree`) and pass `lxml.etree` objects or raw XML strings directly to signxml. Avoid converting to/from `xml.etree.ElementTree` objects.
• gotcha For robust security, always follow the 'See what is signed' principle. After `XMLVerifier.verify()`, explicitly use the `signed_xml` attribute of the return value, as this is the actual data covered by the signature. Also, for specific standards like SAML, it's a best practice to assert the expected signature location using `SignatureConfiguration(location='./')` to prevent signature wrapping attacks.
  Fix: When verifying, access `result.signed_xml` and incorporate `expect_config=SignatureConfiguration(location='./')` in your `verify()` calls where appropriate.
• gotcha The default `XMLVerifier().verify()` behavior trusts any valid X.509 certificate that validates against your system's CA store. For production, you must explicitly establish trust using parameters like `x509_cert` (a pre-shared certificate), `cert_subject_name` (to validate the subject name in the signing certificate), or `ca_pem_file` (a custom CA bundle) to prevent unauthorized signatures.
  Fix: Always specify trust anchors during verification (e.g., `verifier.verify(..., x509_cert=my_trusted_cert)` or `ca_pem_file="/path/to/my_ca.pem")`).
• gotcha XML canonicalization, a crucial step in XML Signature, is highly sensitive to whitespace. Pretty-printing an XML document *after* it has been signed will almost certainly invalidate its signature.
  Fix: Do not pretty-print or reformat signed XML documents if their signatures are to remain valid.

Install

• pip install signxml Install signxml

Imports

• XMLSigner

  from signxml import XMLSigner

• XMLVerifier

  from signxml import XMLVerifier

• etree

  from lxml import etree

  signxml explicitly uses and requires lxml.etree for robust XML handling and security; standard library ElementTree may lead to parsing and namespace issues.

Quickstart

This quickstart demonstrates basic XML signing and verification using `XMLSigner` and `XMLVerifier`. It includes placeholder instructions for generating a test certificate and key using OpenSSL. In production, always load certificates and keys securely and explicitly configure trust for verification. It also highlights the best practice of verifying the `signed_xml` attribute and asserting the signature's expected location.

from lxml import etree
from signxml import XMLSigner, XMLVerifier, SignatureConfiguration
import os

# --- Setup: Generate test certificate and key (requires OpenSSL) ---
# openssl req -x509 -nodes -subj "/CN=test" -days 1 -newkey rsa -keyout privkey.pem -out cert.pem
# In a real application, you would load these from secure storage.

# Ensure cert.pem and privkey.pem exist in the current directory for this example to run.
if not (os.path.exists('cert.pem') and os.path.exists('privkey.pem')):
    print("Please generate 'cert.pem' and 'privkey.pem' using OpenSSL as described in the comments.")
    exit()

cert = open("cert.pem").read()
key = open("privkey.pem").read()

# --- Signing an XML document ---
data_to_sign = "<Test><Data>Hello World!</Data></Test>"
root = etree.fromstring(data_to_sign)

signer = XMLSigner()
signed_root = signer.sign(root, key=key, cert=cert)

print("\n--- Signed XML ---")
print(etree.tostring(signed_root, pretty_print=True).decode())

# --- Verifying the signed XML document ---
verifier = XMLVerifier()

try:
    # It's crucial to explicitly provide the trusted certificate or CA for verification
    # and to ensure the returned data is what was expected to prevent signature wrapping attacks.
    verified_data = verifier.verify(signed_root, x509_cert=cert).signed_xml
    
    print("\n--- Verification Successful! ---")
    print("Signed data content:", etree.tostring(verified_data, pretty_print=False).decode())
    
    # Optionally, assert the signature location (best practice for SAML etc.)
    config = SignatureConfiguration(location='./')
    verifier.verify(signed_root, x509_cert=cert, expect_config=config)
    print("Signature location asserted successfully.")

except Exception as e:
    print(f"\n--- Verification Failed: {e} ---")