Begin XAdES documentation

Author: kislyuk

README.rst

@@ -11,10 +11,11 @@ payload security in `SAML 2.0 <http://en.wikipedia.org/wiki/SAML_2.0>`_ and
 * 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
+* Extensions to sign and verify `XAdES <https://en.wikipedia.org/wiki/XAdES>`_ signatures
 * 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 (3.6-3.10+ and PyPy)
+* Modern Python compatibility (3.6-3.11+ and PyPy)
 * Well-supported, portable, reliable dependencies: `lxml <https://github.com/lxml/lxml>`_,
   `cryptography <https://github.com/pyca/cryptography>`_, `pyOpenSSL <https://github.com/pyca/pyopenssl>`_
 * Comprehensive testing (including the XMLDSig interoperability suite) and `continuous integration
@@ -167,6 +168,38 @@ references for more information:
 * `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>`_
 
+
+XAdES signatures
+~~~~~~~~~~~~~~~~
+SignXML supports signing and verifying documents using `XAdES <https://en.wikipedia.org/wiki/XAdES>`_ signatures:
+
+.. code-block:: python
+
+    from signxml.xades import XAdESSigner, XAdESVerifier, XAdESVerifyResult, digest_algorithms
+    signature_policy = {
+        "Identifier": "MyPolicyIdentifier",
+        "Description": "Hello XAdES",
+        "DigestMethod": digest_algorithms.SHA256,
+        "DigestValue": "Ohixl6upD6av8N7pEvDABhEL6hM=",
+    }
+    signer = XAdESSigner(
+        signature_policy=signature_policy,
+        claimed_roles=["signer"],
+        data_object_format={"Description": "My XAdES signature", "MimeType": "text/xml"},
+        c14n_algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
+    )
+    signed_doc = signer.sign(doc, key=private_key, cert=certificate)
+
+.. code-block:: python
+
+    verifier = XAdESVerifier()
+    verify_results = verifier.verify(
+        signed_doc, x509_cert=certificate, expect_references=3, expect_signature_policy=signature_policy
+    )
+    for verify_result in verify_results:
+        if isinstance(verify_result, XAdESVerifyResult):
+            verify_result.signed_properties  # use this to access parsed XAdES properties
+
 Authors
 -------
 * Andrey Kislyuk