Metadata-Version: 1.1
Name: signxml
Version: 2.7.3
Summary: Python XML Signature library
Home-page: https://github.com/kislyuk/signxml
Author: Andrey Kislyuk
Author-email: kislyuk@gmail.com
License: Apache Software License
Description: SignXML: XML Signature in Python
        ================================
        
        *SignXML* is an implementation of the W3C `XML Signature <http://en.wikipedia.org/wiki/XML_Signature>`_ standard in
        Python. This standard (also known as XMLDSig and `RFC 3275 <http://www.ietf.org/rfc/rfc3275.txt>`_) is used to provide
        payload security in `SAML 2.0 <http://en.wikipedia.org/wiki/SAML_2.0>`_ and
        `WS-Security <https://en.wikipedia.org/wiki/WS-Security>`_, among other uses. Two versions of the standard exist
        (`Version 1.1 <http://www.w3.org/TR/xmldsig-core1/>`_ and `Version 2.0 <http://www.w3.org/TR/xmldsig-core2>`_).
        *SignXML* implements all of the required components of the standard, and most recommended ones. Its features are:
        
        * Use of a libxml2-based XML parser configured to defend against
          `common XML attacks <https://docs.python.org/3/library/xml.html#xml-vulnerabilities>`_ when verifying signatures
        * Extensions to allow signing with and verifying X.509 certificate chains, including hostname/CN validation
        * Support for exclusive XML canonicalization with inclusive prefixes (`InclusiveNamespaces PrefixList
          <http://www.w3.org/TR/xml-exc-c14n/#def-InclusiveNamespaces-PrefixList>`_, required to verify signatures generated by
          some SAML implementations)
        * Modern Python compatibility (2.7-3.8+ and PyPy)
        * Well-supported, portable, reliable dependencies: `lxml <https://github.com/lxml/lxml>`_,
          `cryptography <https://github.com/pyca/cryptography>`_, `eight <https://github.com/kislyuk/eight>`_,
          `pyOpenSSL <https://github.com/pyca/pyopenssl>`_
        * Comprehensive testing (including the XMLDSig interoperability suite) and `continuous integration
          <https://travis-ci.org/XML-Security/signxml>`_
        * Simple interface with useful defaults
        * Compactness, readability, and extensibility
        
        Installation
        ------------
        ::
        
            pip3 install signxml
        
        Note: SignXML depends on `lxml <https://github.com/lxml/lxml>`_ and `cryptography
        <https://github.com/pyca/cryptography>`_, which in turn depend on `OpenSSL <https://www.openssl.org/>`_, `LibXML
        <http://xmlsoft.org/>`_, and Python tools to interface with them. You can install those as follows:
        
        +--------------+----------------------------------------------------------------------------------------------------------------------+
        | OS           | Command                                                                                                              |
        +==============+======================================================================================================================+
        | Ubuntu       | ``apt-get install --no-install-recommends python3-pip python3-wheel python3-setuptools python3-openssl python3-lxml``|
        +--------------+----------------------------------------------------------------------------------------------------------------------+
        | Red Hat,     | ``yum install python3-pip python3-pyOpenSSL python3-lxml``                                                           |
        | Amazon Linux,|                                                                                                                      |
        | CentOS       |                                                                                                                      |
        +--------------+----------------------------------------------------------------------------------------------------------------------+
        | Mac OS       | Install `Homebrew <https://brew.sh>`_, then run ``brew install python``.                                             |
        +--------------+----------------------------------------------------------------------------------------------------------------------+
        
        Synopsis
        --------
        SignXML uses the `lxml ElementTree API <https://lxml.de/tutorial.html>`_ to work with XML data.
        
        .. code-block:: python
        
            from lxml import etree
            from signxml import XMLSigner, XMLVerifier
        
            data_to_sign = "<Test/>"
            cert = open("example.pem").read()
            key = open("example.key").read()
            root = etree.fromstring(data_to_sign)
            signed_root = XMLSigner().sign(root, key=key, cert=cert)
            verified_data = XMLVerifier().verify(signed_root).signed_xml
        
        To make this example self-sufficient for test purposes:
        
        - Generate a test certificate and key using
          ``openssl req -x509 -sha256 -nodes -subj "/CN=test" -days 1 -newkey rsa:2048 -keyout example.key -out example.pem``
          (run ``yum install openssl`` on Red Hat).
        - Pass the ``x509_cert=cert`` keyword argument to ``XMLVerifier.verify()``. (In production, ensure this is replaced with
          the correct configuration for the trusted CA or certificate - this determines which signatures your application trusts.)
        
        .. _verifying-saml-assertions:
        
        Verifying SAML assertions
        ~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Assuming ``metadata.xml`` contains SAML metadata for the assertion source:
        
        .. code-block:: python
        
            from lxml import etree
            from base64 import b64decode
            from signxml import XMLVerifier
        
            with open("metadata.xml", "rb") as fh:
                cert = etree.parse(fh).find("//ds:X509Certificate").text
        
            assertion_data = XMLVerifier().verify(b64decode(assertion_body), x509_cert=cert).signed_xml
        
        .. admonition:: Signing SAML assertions
        
         The SAML assertion schema specifies a location for the enveloped XML signature (between ``<Issuer>`` and
         ``<Subject>``). To sign a SAML assertion in a schema-compliant way, insert a signature placeholder tag at that location
         before calling XMLSigner: ``<ds:Signature Id="placeholder"></ds:Signature>``.
        
        .. admonition:: See what is signed
        
         It is important to understand and follow the best practice rule of "See what is signed" when verifying XML
         signatures. The gist of this rule is: if your application neglects to verify that the information it trusts is
         what was actually signed, the attacker can supply a valid signature but point you to malicious data that wasn't signed
         by that signature. Failure to follow this rule can lead to vulnerability against attacks like
         `SAML signature wrapping <https://www.usenix.org/system/files/conference/usenixsecurity12/sec12-final91.pdf>`_.
        
         In SignXML, you can ensure that the information signed is what you expect to be signed by only trusting the
         data returned by the ``verify()`` method. The ``signed_xml`` attribute of the return value is the XML node or string that
         was signed.
        
         **Recommended reading:** `W3C XML Signature Best Practices for Applications <http://www.w3.org/TR/xmldsig-bestpractices/#practices-applications>`_, `OWASP: On Breaking SAML: Be Whoever You Want to Be <https://www.owasp.org/images/2/28/Breaking_SAML_Be_Whoever_You_Want_to_Be_-_Juraj_Somorovsky%2BChristian_Mainka.pdf>`_, `Duo Finds SAML Vulnerabilities Affecting Multiple Implementations <https://duo.com/blog/duo-finds-saml-vulnerabilities-affecting-multiple-implementations>`_
        
        .. admonition:: Establish trust
        
         If you do not supply any keyword arguments to ``verify()``, the default behavior is to trust **any** valid XML
         signature generated using a valid X.509 certificate trusted by your system's CA store. This means anyone can
         get an SSL certificate and generate a signature that you will trust. To establish trust in the signer, use the
         ``x509_cert`` argument to specify a certificate that was pre-shared out-of-band (e.g. via SAML metadata, as
         shown in *Verifying SAML assertions*), or ``cert_subject_name`` to specify a
         subject name that must be in the signing X.509 certificate given by the signature (verified as if it were a
         domain name), or ``ca_pem_file``/``ca_path`` to give a custom CA.
        
        XML signature methods: enveloped, detached, enveloping
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        The XML Signature specification defines three ways to compose a signature with the data being signed: enveloped,
        detached, and enveloping signature. Enveloped is the default method. To specify the type of signature that you want to
        generate, pass the ``method`` argument to ``sign()``:
        
        .. code-block:: python
        
            signed_root = XMLSigner(method=signxml.methods.detached).sign(root, key=key, cert=cert)
            verified_data = XMLVerifier().verify(signed_root).signed_xml
        
        For detached signatures, the code above will use the ``Id`` or ``ID`` attribute of ``root`` to generate a relative URI
        (``<Reference URI="#value"``). You can also override the value of ``URI`` by passing a ``reference_uri`` argument to
        ``sign()``. To verify a detached signature that refers to an external entity, pass a callable resolver in
        ``XMLVerifier().verify(data, uri_resolver=...)``.
        
        See the `API documentation <https://signxml.readthedocs.io/en/latest/#id4>`_ for more.
        
        XML parsing security and compatibility with ``xml.etree.ElementTree``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        SignXML uses the `lxml <https://github.com/lxml/lxml>`_ ElementTree library, not the
        `ElementTree from Python's standard library <https://docs.python.org/3.8/library/xml.etree.elementtree.html>`_,
        to work with XML. lxml is used due to its superior resistance to XML attacks, as well as XML canonicalization and
        namespace organization features. It is recommended that you pass XML string input directly to signxml before further
        parsing, and use lxml to work with untrusted XML input in general. If you do pass ``xml.etree.ElementTree`` objects to
        SignXML, you should be aware of differences in XML namespace handling between the two libraries. See the following
        references for more information:
        
        * `How do I use lxml safely as a web-service endpoint? <https://lxml.de/FAQ.html#how-do-i-use-lxml-safely-as-a-web-service-endpoint>`_
        * `ElementTree compatibility of lxml.etree <https://lxml.de/compatibility.html>`_
        * `XML Signatures with Python ElementTree <https://technotes.shemyak.com/posts/xml-signatures-with-python-elementtree>`_
        
        Authors
        -------
        * Andrey Kislyuk
        
        Links
        -----
        * `Project home page (GitHub) <https://github.com/XML-Security/signxml>`_
        * `Documentation (Read the Docs) <https://signxml.readthedocs.io/en/latest/>`_
        * `Package distribution (PyPI) <https://pypi.python.org/pypi/signxml>`_
        * `Change log <https://github.com/XML-Security/signxml/blob/master/Changes.rst>`_
        * `List of W3C XML Signature standards and drafts <http://www.w3.org/TR/#tr_XML_Signature>`_
        * `W3C Recommendation: XML Signature Syntax and Processing Version 1.1 <http://www.w3.org/TR/xmldsig-core1>`_
        * `W3C Working Group Note: XML Signature Syntax and Processing Version 2.0 <http://www.w3.org/TR/xmldsig-core2>`_
        * `W3C Working Group Note: XML Security 2.0 Requirements and Design Considerations <https://www.w3.org/TR/2013/NOTE-xmlsec-reqs2-20130411/>`_
        * `W3C Working Group Note: XML Signature Best Practices <http://www.w3.org/TR/xmldsig-bestpractices/>`_
        * `XML-Signature Interoperability <http://www.w3.org/Signature/2001/04/05-xmldsig-interop.html>`_
        * `W3C Working Group Note: Test Cases for C14N 1.1 and XMLDSig Interoperability <http://www.w3.org/TR/xmldsig2ed-tests/>`_
        * `XMLSec: Related links <https://www.aleksey.com/xmlsec/related.html>`_
        * `OWASP SAML Security Cheat Sheet <https://www.owasp.org/index.php/SAML_Security_Cheat_Sheet>`_
        * `Okta Developer Docs: SAML <https://developer.okta.com/standards/SAML/>`_
        
        Bugs
        ~~~~
        Please report bugs, issues, feature requests, etc. on `GitHub <https://github.com/XML-Security/signxml/issues>`_.
        
        License
        -------
        Licensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
        
        .. image:: https://github.com/XML-Security/signxml/workflows/Test%20suite/badge.svg
                :target: https://github.com/XML-Security/signxml/actions
        .. image:: https://codecov.io/github/XML-Security/signxml/coverage.svg?branch=master
                :target: https://codecov.io/github/XML-Security/signxml?branch=master
        .. image:: https://img.shields.io/pypi/v/signxml.svg
                :target: https://pypi.python.org/pypi/signxml
        .. image:: https://img.shields.io/pypi/l/signxml.svg
                :target: https://pypi.python.org/pypi/signxml
        .. image:: https://readthedocs.org/projects/signxml/badge/?version=latest
                :target: https://signxml.readthedocs.io/
        
Platform: MacOS X
Platform: Posix
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
