Skip to main content

Minimal XML signature and verification, intended for use with SAML2

Project description

minisignxml

Code style: black CircleCI

Python library to sign and verify XML documents.

This library, on purpose, only supports a limited part of the xmldsig specification. It is mainly aimed at allowing SAML documents to be signed and verified.

Supported features:

  • Simple API.
  • Only support enveloped signatures (http://www.w3.org/2000/09/xmldsig#enveloped-signature)
  • Require and only support exclusive XML canonincalization without comments (http://www.w3.org/2001/10/xml-exc-c14n#)
  • Support SHA-256 (default) and SHA-1 (for compatibility, not recommended) for signing and digest (https://www.w3.org/2000/09/xmldsig#sha1, https://www.w3.org/2000/09/xmldsig#rsa-sha1, http://www.w3.org/2001/04/xmlenc#sha256, http://www.w3.org/2001/04/xmldsig-more#rsa-sha256)
  • Only support X509 certificates and RSA private keys
  • Uses lxml for XML handling and cryptography for cryptography.
  • Only supports a single signature, with a single reference in a document.
  • Support certificate rollover by providing multiple certificates when verifying a document.

minisignxml performs no IO and you have to manage and load the keys/certificates yourself.

API

Signing

minisignxml.sign.sign

def sign(
    *,
    element: Element,
    private_key: RSAPrivateKey,
    certificate: Certificate,
    config: SigningConfig = SigningConfig.default(),
    index: int = 0,
    attribute: str = "ID"
) -> bytes:

Signs the given lxml.etree._Element with the given cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey private key, embedding the cryptography.x509.Certificate in the signature. Use minisignxml.config.SigningConfig to control the hash algorithms uses (default is SHA-256). The index controls at which index the signature element is appended to the element.

If the element passed in does not have an attribute matching attribute, an exception is raised. It is the callers responsibility to ensure the value of the attribute attribute of the Element is unique for the whole document.

Returns bytes containing the serialized XML including the signature.

SigningConfig

minisignxml.config.SigningConfig is a dataclass with the following fields:

  • signature_method: A cryptography.hazmat.primitives.hashes.HashAlgorithm to use for the signature. Defaults to an instance of cryptography.hazmat.primitives.hashes.SHA256.
  • digest_method: A cryptography.hazmat.primitives.hashes.HashAlgorithm to use for the content digest. Defaults to an instance of cryptography.hazmat.primitives.hashes.SHA256.

Verifying

minisignxml.verify.extract_verified_element

def extract_verified_element(
    *, 
    xml: bytes, 
    certificate: Certificate,  
    config: VerifyConfig=VerifyConfig.default(),
    attribute: str = "ID"
) -> Element:

Verifies that the XML document given (as bytes) is correctly signed using the private key of the cryptography.x509.Certificate provided.

A successful call to extract_verified_element does not guarantee the integrity of the whole document passed to it via the xml parameter. Only the sub-tree returned from the function has been verified. The caller should use the returned lxml.etree._Element for further processing.

Raises an exception (see minisignxml.errors, though other exceptions such as ValueError, KeyError or others may also be raised) if the verification failed. Otherwise returns the signed lxml.etree._Element (not necessarily the whole document passed to extract_verified_element), with the signature removed.

You can control the allowed signature and digest method by using a custom VerifyConfig instance. By default only SHA-256 is allowed.

minisignxml.verify.extract_verified_element_and_certificate

def extract_verified_element_and_certificate(
    *, 
    xml: bytes, 
    certificates: Collection[Certificate],  
    config: VerifyConfig=VerifyConfig.default(),
    attribute: str = "ID"
) -> Tuple[Element, Certificate]:

Similar to extract_verified_element, but allows specifying multiple certificates to aid certificate rollover. The certificate that was used to sign the xml will be returned with the verified element.

VerifyConfig

minisignxml.config.SigningConfig is a dataclass with the following fields:

  • allowed_signature_methods: A container of cryptography.hazmat.primitives.hashes.HashAlgorithm types to allow for signing. Defaults to {cryptography.hazmat.primitives.hashes.SHA256}.
  • allowed_digest_methods: A container of cryptography.hazmat.primitives.hashes.HashAlgorithm types to allow for the content digest. Defaults to {cryptography.hazmat.primitives.hashes.SHA256}.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

minisignxml-24.6.tar.gz (8.0 kB view details)

Uploaded Source

Built Distribution

minisignxml-24.6-py3-none-any.whl (9.5 kB view details)

Uploaded Python 3

File details

Details for the file minisignxml-24.6.tar.gz.

File metadata

  • Download URL: minisignxml-24.6.tar.gz
  • Upload date:
  • Size: 8.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.4

File hashes

Hashes for minisignxml-24.6.tar.gz
Algorithm Hash digest
SHA256 7bb2de078793cdf7b7835047b79d215eb2a7e4c948653f6ecee2d95e1674f114
MD5 50bf5eb5f08dbbdda7e67083b956b70c
BLAKE2b-256 88f170fa7a930d4210558b22c6dc01df011895e589f3e7f6716f9689fa06f8ac

See more details on using hashes here.

Provenance

File details

Details for the file minisignxml-24.6-py3-none-any.whl.

File metadata

  • Download URL: minisignxml-24.6-py3-none-any.whl
  • Upload date:
  • Size: 9.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.4

File hashes

Hashes for minisignxml-24.6-py3-none-any.whl
Algorithm Hash digest
SHA256 83d61745607f523783ac6c8638e2ec7a9d16f3ed178c1c4b7af9bfd02c51e944
MD5 76348faff2fc5b4d3e3186156b771d2d
BLAKE2b-256 919f4af6969a33cc257ee6124aa13b49355b9b04d192653fe8bbed7e55a03d2a

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page