Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท WS-Security and Standards

WS-Security: XML Signatures and Encryption

Understand how SOAP messages are signed (XML-DSig) and encrypted (XML Encryption), what canonicalization and key wrapping do, and try the same ideas with node:crypto stand-ins.

Authentication tells the service who you are. Signatures prove that a message came from a particular key holder and was not altered on the way. Encryption hides content from everyone but the intended receiver. WS-Security uses two W3C standards for this: XML Signature (XML-DSig) and XML Encryption, and attaches the results to the wsse:Security header you met in the previous lesson.

Our editor has no XML-DSig library, no certificates and no WS-Security toolkit. The two runnable examples below therefore use node:crypto to demonstrate the same mechanism (digest, sign, verify, hybrid encryption) on a simplified message. They are labelled stand-ins: the real XML-DSig syntax is shown read-only.

How a signature works

A signature answers one question: "has this part of the message changed, and who vouches for it?" The recipe, in steps:

  1. Choose what to sign (the Body, the Timestamp, some headers). Each item is a reference.
  2. Canonicalize each item: rewrite the XML into one agreed byte form (attribute order, whitespace in tags, namespace declarations normalized), so harmless formatting changes do not break the signature. The standard algorithm is Exclusive XML Canonicalization (exc-c14n).
  3. Digest each canonical item (SHA-256) and put the digests in a SignedInfo element.
  4. Sign SignedInfo with the sender's private key (RSA-SHA256, or ECDSA) and put the result in SignatureValue.
  5. Add a KeyInfo telling the receiver which key or certificate to use.

The receiver repeats the digest of each referenced item, compares it with SignedInfo, and verifies SignatureValue with the public key.

XML
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:SignedInfo>
    <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
    <ds:Reference URI="#Body-1">
      <ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms>
      <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
      <ds:DigestValue>Zm9vYmFy...</ds:DigestValue>
    </ds:Reference>
  </ds:SignedInfo>
  <ds:SignatureValue>MIIB...</ds:SignatureValue>
  <ds:KeyInfo><wsse:SecurityTokenReference>...</wsse:SecurityTokenReference></ds:KeyInfo>
</ds:Signature>

The URI="#Body-1" points at an element carrying wsu:Id="Body-1". Signing the Timestamp too stops an attacker from extending its life.

A signature in miniature

This program follows the same steps with a simple stand-in: whitespace-normalization for canonicalization, SHA-256 for the digest, and RSA for the signature. It shows the two properties that matter: tampering is detected, and harmless formatting is not.

Node.js Sign, verify and detect tampering

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last line is the key insight: an attacker who changes the body can also recompute the digest, but cannot recompute the signature without the private key, so sigOk becomes false.

How encryption works

Encrypting a whole message with RSA is impossible (RSA only handles small data) and slow. XML Encryption uses a hybrid scheme, the same one used by TLS and PGP:

  1. Generate a random symmetric key (AES-128/256).
  2. Encrypt the Body (or any element) with AES (usually GCM or CBC mode). The result replaces the element as xenc:EncryptedData.
  3. Encrypt (wrap) the AES key with the receiver's public RSA key (RSA-OAEP) and put it in xenc:EncryptedKey in the Security header.

Only the holder of the receiver's private key can unwrap the AES key and decrypt the content. You can encrypt just the sensitive fields (a card number) and leave the rest readable by gateways, which is the advantage over TLS.

Node.js Hybrid encryption of a Body

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

GCM is an authenticated mode: a modified ciphertext is detected. Older WS-Security deployments use AES-CBC, which does not authenticate by itself and has been the source of padding-oracle attacks; prefer GCM, or always sign as well.

Order matters

Sign-then-encrypt and encrypt-then-sign have different properties. WS-Security allows both; the security policy of the service says which. A common safe rule: encrypt the parts that need secrecy and sign the parts that need integrity, including the timestamp, and sign the encrypted form when the signature must survive without the key.

Key material and certificates

Real deployments exchange X.509 certificates: the sender signs with its private key and includes (or references) its certificate; the receiver trusts a certificate authority or a pinned certificate. The keys live in a keystore (Java .jks / .p12, Windows certificate store). The WS-Security header refers to them with a SecurityTokenReference, either embedding a BinarySecurityToken or naming the certificate by thumbprint or issuer and serial. Expired certificates, wrong trust stores and mismatched algorithms cause most production failures, so log which algorithm and key identifier each side expects.

Do not write your own XML canonicalization or signature verification for production. Subtle bugs (signature wrapping attacks, where an attacker moves the signed element and adds a forged one) have broken many implementations. Use a maintained library and verify that the element you process is the element that was signed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does XML signing canonicalize the XML first?

    Canonicalization produces one agreed byte form, so whitespace in tags or attribute order does not break a valid signature.
  2. 2. An attacker changes the amount in a signed Body and recomputes the digest. What stops the forgery?

    The digest can be recomputed by anyone, but the signature over the digest cannot be forged without the private key.
  3. 3. In XML Encryption, what is wrapped with the receiver's public RSA key?

    Hybrid encryption: data is encrypted with a symmetric key, and that key is encrypted with RSA.
  4. 4. What advantage does message-level encryption have over TLS?

    Only the intended receiver can read the encrypted parts, even after passing intermediaries, and unencrypted parts can still be routed.
  5. 5. Which is a recommended practice?

    Signing the timestamp and checking the signed element identity protects against replay and signature-wrapping attacks.

Summary

  • XML-DSig signs canonicalized references (digest), then signs the SignedInfo; verification repeats the steps with the public key.
  • XML Encryption is hybrid: AES encrypts the data, RSA wraps the AES key.
  • Signatures give integrity and origin; encryption gives confidentiality; use both where needed and sign the timestamp.
  • Certificates, keystores and algorithm mismatches are the usual causes of failures.
  • Use maintained libraries; never write your own canonicalization or verification.

Next: WS-Addressing and Reliable Messaging