docs: add WS-Security (WSSE) UsernameToken+Sign+Encrypt example

Add a recipe for a common WS-Security 1.1 shape (UsernameToken plus a
signed Body plus a detached EncryptedKey/encrypted Body) not covered by
the existing sign/encrypt examples. Documents why
EncryptionContext.encrypt_binary/encrypt_xml reject an EncryptedKey
template node (confirmed against xmlsec1 1.2.39), hence the manual
wrap/unwrap via `cryptography`, and that sign-then-encrypt vs
encrypt-then-sign requires opposite decrypt/verify ordering on the
receiving side. Adds `cryptography` to requirements-test.txt since the
new examples depend on it.

Author: ja-juarez-cruz

doc/source/examples.rst

@@ -33,3 +33,66 @@ Verify-Binary
 -------------
 
 .. literalinclude:: examples/verify_binary.py
+
+
+WS-Security (WSSE): UsernameToken, Sign, Encrypt
+--------------------------------------------------
+
+These two scripts show one way to build and process a WS-Security secured
+SOAP envelope with xmlsec: a ``UsernameToken`` plus an XML signature over
+the Body plus an XML encryption of the Body, using a "detached"
+``EncryptedKey`` under ``wsse:Security`` (the shape most SOAP stacks
+expect for WS-Security 1.1), instead of the ``EncryptedKey``-nested-inside-
+``EncryptedData`` shape that :func:`~xmlsec.EncryptionContext.encrypt_xml`
+produces by default.
+
+xmlsec's ``EncryptionContext.encrypt_binary``/``encrypt_xml`` only accept
+an ``xenc:EncryptedData`` node as their template, so they cannot fill in a
+detached ``EncryptedKey`` directly; these examples wrap/unwrap the AES
+session key with the ``cryptography`` package instead, while still using
+xmlsec's template helpers to build the element and xmlsec's own contexts
+to sign/verify and encrypt/decrypt the Body. See the docstrings in each
+script for the full explanation, including why the two scripts process
+Sign/Encrypt and Decrypt/Verify in mirrored (not identical) order.
+
+.. warning::
+
+   ``wssekey.pem`` and ``wssecert.pem`` in this directory are a self-signed
+   key pair generated only for these examples (the certificate's
+   Subject/Issuer CN says as much: "test key, DO NOT USE IN PRODUCTION").
+   Do not reuse them for anything real -- generate your own pair, e.g.::
+
+       openssl req -x509 -newkey rsa:2048 -nodes -days 3650 \
+           -keyout wssekey.pem -out wssecert.pem \
+           -subj "/CN=your identity here"
+
+To keep the example short, both scripts reuse this *same* key pair for
+every role, but in a real deployment each party has its own key pair and
+only ever holds its own private key plus the other side's public
+certificate:
+
+* The **sender** (whoever calls ``sign_body``) signs with its own private
+  key -- ``signing_key_file`` in ``wsse_outgoing.py``. Only the sender
+  ever holds this key.
+* To **encrypt** the Body, the sender needs the *recipient's* public
+  certificate -- ``recipient_cert_file`` in ``encrypt_body``. This is the
+  public cert of whoever will receive and decrypt the message (the
+  service being called, or the calling client, depending on which
+  direction the message flows), obtained out-of-band ahead of time.
+* On the receiving side, ``verify_signature`` needs the *sender's* public
+  certificate, to check who signed the message. ``unwrap_session_key``,
+  on the other hand, needs the *recipient's own* private key, to decrypt
+  the session key that was encrypted for it.
+
+In other words: a real integration needs two independent key pairs, one
+per party, not the single shared pair used here for brevity.
+
+Outgoing (build a secured request)
++++++++++++++++++++++++++++++++++
+
+.. literalinclude:: examples/wsse_outgoing.py
+
+Incoming (process a secured response)
+++++++++++++++++++++++++++++++++++++
+
+.. literalinclude:: examples/wsse_incoming.py

doc/source/examples/wsse-secured.xml

@@ -0,0 +1,32 @@
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ex="urn:example:wsse-demo"><soapenv:Header><wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#" Id="body-key">
+<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
+<CipherData>
+<CipherValue>pJoXEOU2aFv0uy/p4DmrewBLwPC4EnSifah2uyjay94lD2o9DxH+KFA67CqbM+sqb+Uw1l/ktBw81Hvx+TIwAzhDMJqQwPR97bANjfnEb04EiEdxqUMMnzJunx9xCAqNbU3mPxIVtchqqq3IN2MSY8nGZXFZzrFGt3GWfBrU84JjT8Z6Qsax1/60Evx/SIIhPb+J+e0GauOuqqUvulyg8A2CTLkPZDrbsXDQxyyvl6Hs1JO7nYzufmmy8dlt6L22ryaTQeE179UQhA0g1xxi4urqWW8c4p7DyFfGOYSV6ZIM0QL26ExGqfmJj47crnoeLoB7C1apeOBx4PJrLMSdAA==</CipherValue>
+</CipherData>
+<ReferenceList><DataReference URI="#body-data"/></ReferenceList></EncryptedKey>
+<wsse:UsernameToken><wsse:Username>demo-user</wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">demo-password</wsse:Password></wsse:UsernameToken><Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
+<SignedInfo>
+<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
+<Reference URI="#body">
+<Transforms>
+<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+</Transforms>
+<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
+<DigestValue>CVIISH/pUxaPBQOdrr5VmOvwb+Yc19VyJRaTc8y7q0k=</DigestValue>
+</Reference>
+</SignedInfo>
+<SignatureValue>YPw0lnnztPmRCQGdr7UvsqLDVKVjcFjo5SbBfC9ZqhCvyP+5mBChj/G8gDC1tPuV
+L8t20xUtHpO6qjW4emnncXHTZqnaD9BGqGzl6KEX0tzA16nkvTaVxfc52h4vc+Xv
+rUl0wfwkK0bxkVKTN8cwmUYtH0MNEENG5ogP4ql6A3yyGZamxGSvoRHmnM+wBInd
+cUKlTM7OinB70kDzKjkKu/ZfNa8EZIfy2VzAS5u01Co9ZKdaAd9ahyre8Y0MDscc
+LokWJ0A88dCvtdq06ymxHtQTufz4ZiTsH6G9zUWK7aoZKDxO/d/wYr8SJDZ0P8BC
+fCtKC9GM5w89FFMRwmZDGg==</SignatureValue>
+</Signature></wsse:Security></soapenv:Header><soapenv:Body xmlns:ns0="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" ns0:Id="body"><xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Type="http://www.w3.org/2001/04/xmlenc#Content" Id="body-data">
+<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
+<xenc:CipherData>
+<xenc:CipherValue>aplU5Dg8X8x19a7O2XlV1PouZe1PEl2Lh+k2l79OKnp4ddD7p3XGpAHNXMwN13lx
+VSyP3+JBn+q5NvLvHJwdEqDoHntUAVC+c/4vTABfWdH3qEq8ObG4QZiAbw9uncvm
+utZyrJsZcl9org9p1QWCjw==</xenc:CipherValue>
+</xenc:CipherData>
+</xenc:EncryptedData></soapenv:Body></soapenv:Envelope>

doc/source/examples/wsse-tmpl.xml

@@ -0,0 +1,10 @@
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+                   xmlns:ex="urn:example:wsse-demo">
+    <soapenv:Header/>
+    <soapenv:Body>
+        <ex:ExampleRequest>
+            <ex:Field1>hello</ex:Field1>
+            <ex:Field2>42</ex:Field2>
+        </ex:ExampleRequest>
+    </soapenv:Body>
+</soapenv:Envelope>

doc/source/examples/wsse_incoming.py

@@ -0,0 +1,85 @@
+"""Process a WS-Security (WSSE) secured SOAP response: Decrypt + Verify.
+
+Companion to ``wsse_outgoing.py``. Loads a pre-built, signed-then-encrypted
+envelope (``wsse-secured.xml``, produced the same way ``wsse_outgoing.py``
+builds one) and reverses the two operations.
+
+Order matters and is the mirror image of how the message was built: the
+sender in this example signed the Body *before* encrypting it, so the
+Signature's digest covers the plaintext Body. Verifying against the
+still-encrypted Body would always fail, so this example decrypts first
+(which restores the original Body content in place) and verifies second.
+If a peer instead encrypts-then-signs (common for some backend-originated
+responses, since it lets the signature cover exactly the bytes on the
+wire), reverse the two steps here: verify first, decrypt second.
+"""
+
+import base64
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+from lxml import etree
+
+import xmlsec
+
+NS = {
+    'soapenv': 'http://schemas.xmlsoap.org/soap/envelope/',
+    'wsse': 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd',
+    'wsu': 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd',
+    'ds': 'http://www.w3.org/2000/09/xmldsig#',
+    'xenc': 'http://www.w3.org/2001/04/xmlenc#',
+}
+
+# Must match the peer's choices; see the note in wsse_outgoing.py about
+# legacy (sha1 / tripledes / rsa-1_5) variants.
+KEY_UNWRAP_HASH = hashes.SHA256()
+
+
+def unwrap_session_key(security, private_key_file):
+    """Recover the AES session key from the detached EncryptedKey.
+
+    xmlsec's decrypt() only understands EncryptedData nodes (the mirror
+    image of the encrypt_binary/encrypt_xml limitation described in
+    wsse_outgoing.py), so a detached EncryptedKey has to be unwrapped by
+    hand with the recipient's RSA private key.
+    """
+    with open(private_key_file, 'rb') as fp:
+        private_key = serialization.load_pem_private_key(fp.read(), password=None)
+
+    enc_key_node = security.find('xenc:EncryptedKey', NS)
+    cipher_value = enc_key_node.find('.//xenc:CipherValue', NS)
+    wrapped_key = base64.b64decode(cipher_value.text)
+
+    return private_key.decrypt(
+        wrapped_key,
+        padding.OAEP(mgf=padding.MGF1(algorithm=KEY_UNWRAP_HASH), algorithm=KEY_UNWRAP_HASH, label=None),
+    )
+
+
+def decrypt_body(envelope, security, session_key_bytes):
+    enc_data_node = envelope.find('.//soapenv:Body/xenc:EncryptedData', NS)
+    ctx = xmlsec.EncryptionContext()
+    ctx.key = xmlsec.Key.from_binary_data(xmlsec.constants.KeyDataAes, session_key_bytes)
+    ctx.decrypt(enc_data_node)
+
+
+def verify_signature(envelope, sender_cert_file):
+    xmlsec.tree.add_ids(envelope, [f'{{{NS["wsu"]}}}Id', 'Id', 'id'])
+    signature_node = envelope.find('.//ds:Signature', NS)
+    ctx = xmlsec.SignatureContext()
+    ctx.key = xmlsec.Key.from_file(sender_cert_file, xmlsec.constants.KeyDataFormatCertPem)
+    ctx.verify(signature_node)
+
+
+if __name__ == '__main__':
+    with open('wsse-secured.xml', 'rb') as fp:
+        envelope = etree.parse(fp).getroot()
+
+    security = envelope.find('.//wsse:Security', NS)
+
+    session_key_bytes = unwrap_session_key(security, private_key_file='wssekey.pem')
+    decrypt_body(envelope, security, session_key_bytes)
+    verify_signature(envelope, sender_cert_file='wssecert.pem')
+
+    print('Signature OK. Decrypted Body:')
+    print(etree.tostring(envelope.find('soapenv:Body', NS)).decode())

doc/source/examples/wsse_outgoing.py

@@ -0,0 +1,159 @@
+"""Build a WS-Security (WSSE) secured SOAP request: UsernameToken + Sign + Encrypt.
+
+xmlsec exposes XML-DSig and XML-Enc primitives, but WS-Security profiles
+build a specific *combination* of them inside a SOAP ``<wsse:Security>``
+header that xmlsec does not template for you. This example shows one
+common, interoperable combination:
+
+1. A UsernameToken (plain-text password) in the Security header.
+2. An enveloped-style XML signature over the SOAP Body, referenced by an
+   ``Id`` attribute (WS-Security "Reference" pattern, not the enveloped
+   XPath transform).
+3. A "detached" ``xenc:EncryptedKey`` living directly under
+   ``wsse:Security`` (not nested inside the ``EncryptedData`` it protects,
+   which is where ``encrypt_xml``/``encrypt_binary`` would normally put
+   it). This is the shape most SOAP stacks expect for WS-Security 1.1.
+
+Because that detached ``EncryptedKey`` is not part of the ``EncryptedData``
+tree, xmlsec's ``EncryptionContext.encrypt_binary``/``encrypt_xml`` cannot
+fill it in directly -- both require an ``xenc:EncryptedData`` node as the
+target template (see ``xmlSecEncCtxEncDataNodeRead`` in xmlsec1, which
+rejects an ``EncryptedKey`` node with "invalid node"). So this example
+wraps the AES session key with RSA-OAEP using the ``cryptography`` package
+and places the result in the ``EncryptedKey``'s ``CipherValue`` by hand,
+while still using xmlsec's own template helpers to build the element and
+xmlsec's ``EncryptionContext`` to encrypt the Body itself.
+
+Order matters: this example signs the Body *before* encrypting it, so the
+signature covers the plaintext. A receiver must therefore decrypt first
+and verify second -- see ``wsse_incoming.py``. If you instead need to
+encrypt before signing (e.g. because a peer's stack requires the signature
+to cover ciphertext), reverse the two steps below and sign the
+``EncryptedData``'s ``Id`` instead of the Body's.
+"""
+
+import base64
+import os
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding
+from lxml import etree
+
+import xmlsec
+
+NS = {
+    'soapenv': 'http://schemas.xmlsoap.org/soap/envelope/',
+    'wsse': 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd',
+    'wsu': 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd',
+    'ds': 'http://www.w3.org/2000/09/xmldsig#',
+    'xenc': 'http://www.w3.org/2001/04/xmlenc#',
+}
+
+# Recommended defaults. Some legacy WS-Security 1.0-era stacks only accept
+# rsa-sha1 / tripledes-cbc / rsa-1_5 -- swap the constants below (and the
+# `cryptography` padding/hash objects to match) if you must interop with
+# one of those, but prefer these unless you are told otherwise.
+SIGNATURE_TRANSFORM = xmlsec.constants.TransformRsaSha256
+DIGEST_TRANSFORM = xmlsec.constants.TransformSha256
+BODY_ENCRYPTION_TRANSFORM = xmlsec.constants.TransformAes128Cbc
+KEY_WRAP_HASH = hashes.SHA256()
+
+
+def add_security_header(envelope):
+    header = envelope.find('soapenv:Header', NS)
+    if header is None:
+        header = etree.SubElement(envelope, f'{{{NS["soapenv"]}}}Header')
+        envelope.insert(0, header)
+    return etree.SubElement(
+        header,
+        f'{{{NS["wsse"]}}}Security',
+        nsmap={'wsse': NS['wsse'], 'wsu': NS['wsu']},
+    )
+
+
+def add_username_token(security, username, password):
+    token = etree.SubElement(security, f'{{{NS["wsse"]}}}UsernameToken')
+    etree.SubElement(token, f'{{{NS["wsse"]}}}Username').text = username
+    password_elem = etree.SubElement(token, f'{{{NS["wsse"]}}}Password')
+    password_elem.set(
+        'Type',
+        'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText',
+    )
+    password_elem.text = password
+    return token
+
+
+def sign_body(envelope, security, signing_key_file, body_id='body'):
+    body = envelope.find('soapenv:Body', NS)
+    body.set(f'{{{NS["wsu"]}}}Id', body_id)
+    xmlsec.tree.add_ids(envelope, [f'{{{NS["wsu"]}}}Id', 'Id', 'id'])
+
+    signature_node = xmlsec.template.create(envelope, xmlsec.constants.TransformExclC14N, SIGNATURE_TRANSFORM)
+    security.append(signature_node)
+
+    reference = xmlsec.template.add_reference(signature_node, DIGEST_TRANSFORM, uri='#' + body_id)
+    xmlsec.template.add_transform(reference, xmlsec.constants.TransformExclC14N)
+
+    ctx = xmlsec.SignatureContext()
+    ctx.key = xmlsec.Key.from_file(signing_key_file, xmlsec.constants.KeyDataFormatPem)
+    ctx.sign(signature_node)
+    return signature_node
+
+
+def encrypt_body(envelope, security, recipient_cert_file, data_id='body-data', key_id='body-key'):
+    body = envelope.find('soapenv:Body', NS)
+
+    with open(recipient_cert_file, 'rb') as fp:
+        recipient_cert = x509.load_pem_x509_certificate(fp.read())
+
+    # 1. Generate a random session key and use it to encrypt the Body
+    #    content with xmlsec, exactly like the plain `encrypt.py` example.
+    session_key_bytes = os.urandom(16)  # 16 bytes = AES-128
+
+    enc_data_template = xmlsec.template.encrypted_data_create(
+        body,
+        BODY_ENCRYPTION_TRANSFORM,
+        type=xmlsec.constants.TypeEncContent,
+        ns='xenc',
+    )
+    enc_data_template.set('Id', data_id)
+    xmlsec.template.encrypted_data_ensure_cipher_value(enc_data_template)
+
+    enc_ctx = xmlsec.EncryptionContext()
+    enc_ctx.key = xmlsec.Key.from_binary_data(xmlsec.constants.KeyDataAes, session_key_bytes)
+    enc_ctx.encrypt_xml(enc_data_template, body)
+
+    # 2. Wrap the session key with the recipient's RSA public key ourselves
+    #    (see module docstring for why xmlsec can't do this part for a
+    #    detached EncryptedKey), and place it directly under Security.
+    wrapped_key = recipient_cert.public_key().encrypt(
+        session_key_bytes,
+        padding.OAEP(mgf=padding.MGF1(algorithm=KEY_WRAP_HASH), algorithm=KEY_WRAP_HASH, label=None),
+    )
+
+    enc_key_node = xmlsec.template.add_encrypted_key(security, xmlsec.constants.TransformRsaOaep, id=key_id)
+    xmlsec.template.encrypted_data_ensure_cipher_value(enc_key_node).text = base64.b64encode(wrapped_key).decode()
+
+    reference_list = etree.SubElement(enc_key_node, f'{{{NS["xenc"]}}}ReferenceList')
+    etree.SubElement(reference_list, f'{{{NS["xenc"]}}}DataReference').set('URI', '#' + data_id)
+
+    # A detached EncryptedKey must come before anything that references it,
+    # so it is expected as the first child of Security by most consumers.
+    security.remove(enc_key_node)
+    security.insert(0, enc_key_node)
+
+
+if __name__ == '__main__':
+    with open('wsse-tmpl.xml') as fp:
+        envelope = etree.parse(fp, etree.XMLParser(remove_blank_text=True)).getroot()
+
+    security = add_security_header(envelope)
+    add_username_token(security, username='demo-user', password='demo-password')
+    sign_body(envelope, security, signing_key_file='wssekey.pem')
+    encrypt_body(envelope, security, recipient_cert_file='wssecert.pem')
+
+    # NOTE: do not pretty-print before/after signing -- inserting
+    # whitespace-only text nodes changes what exclusive C14N canonicalizes,
+    # so a pretty-printed copy would no longer verify.
+    print(etree.tostring(envelope).decode())

doc/source/examples/wssecert.pem

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDdTCCAl2gAwIBAgIUDfID7AItWUsM2kHiLPcGZNb9rJMwDQYJKoZIhvcNAQEL
+BQAwSjFIMEYGA1UEAww/cHl0aG9uLXhtbHNlYyBXU1NFIGV4YW1wbGUgKHRlc3Qg
+a2V5LCBETyBOT1QgVVNFIElOIFBST0RVQ1RJT04pMB4XDTI2MDkyMjE1NDQwMloX
+DTM2MDkxOTE1NDQwMlowSjFIMEYGA1UEAww/cHl0aG9uLXhtbHNlYyBXU1NFIGV4
+YW1wbGUgKHRlc3Qga2V5LCBETyBOT1QgVVNFIElOIFBST0RVQ1RJT04pMIIBIjAN
+BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5B6SRkKzfIQzp8Iqx1FgMqr8QRnK
+NNvl+7NdmG493uWGyC2lucgB6mtSh4oEdrPTeLaXkk12TKLv/TMHFzUCjdnQniJo
+gvwB3abdSxl7F8wRAgzDok56E00PZqpsDz+g8NAP6xBwA9CNgUTmWh9OMJeiTUXC
+NBgYBldjm8CyqF/DONRB49+vHIV/ciSzvqU7YudG4A6wcyoaokn4X/eIgt8Ar0B4
+WjwjGKyntvB26Fk7nQiFJ7V0FLlXYob9TXe6Ff4H5fvMcmVeEVfpLN/ryojFTh8F
+VoDoqjV5sneheCBNW3rGygAHwNBxLkJSICHl/LaRl4czObXCf6TNF3ByawIDAQAB
+o1MwUTAdBgNVHQ4EFgQULqjD0z8t1wcR6xWcNjqZFtaRylwwHwYDVR0jBBgwFoAU
+LqjD0z8t1wcR6xWcNjqZFtaRylwwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0B
+AQsFAAOCAQEAXVxQdjpnMsJb7v/hBYVbuUxFvwSB+x9cGaux/g+louSr1/Q7fZ+c
+/j3Ai0DGZ8k8xcKpPHFr2/VcruB9OLF6c86enCcx85naU2g+u3TqVllQ6sN2I2N5
+bj5aHF3HRkJt7vI7ilg+efjOgfRa66U71M4yEgfgWt8rHEQoT9oC2zWUyGX+0kp+
+bqm1a0MqrCmT/mL0cuhwg5gawz4bnuXSU6+XiczKtWrdnMf6dejbZho9YOcp8GN3
+UJ+uEAQTIlN32wQQFBIBEidEYp4Q1Dg+0wkEQ/2uXKE9+QkizCobiJ5qRncflnlr
+FVcTWKDVeTK/2av0S3GCnvZ832i1+GThJw==
+-----END CERTIFICATE-----