skip to content

WS-Security

5 roadmaps6 questions

A wsse:Security header carries UsernameToken, X.509 or SAML tokens, a Timestamp, and signatures or encryption over chosen parts. Interviewers ask because it protects a message across every hop.

part ofAPI stylesoverview, primer and where to startread it →
on this pageshow

explore

questions

6

In WS-Security, what is the wsse:Security SOAP header block, and what kinds of security information does it carry?

level: juniorimportance: must knowfreq 30%

answer

  1. a SOAP header block, not a transport
  2. aimed at one actor or role
  3. tokens, timestamp, signatures, keys
  4. one block per recipient
  5. new children go on top

basics

~20 s

wsse:Security is the SOAP header block WS-Security defines for security data aimed at one recipient: tokens such as a UsernameToken, an X.509 certificate or a SAML assertion, a wsu:Timestamp, and the signatures and encryption keys protecting chosen parts.

solid answer

~40 s

The OASIS **WSS: SOAP Message Security 1.1.1** specification defines `<wsse:Security>` as a SOAP header block that carries security information for one recipient, named by a SOAP 1.1 `actor` or SOAP 1.2 `role` attribute: an intermediary or the ultimate receiver. Inside it go **security tokens** (`wsse:UsernameToken`, a `wsse:BinarySecurityToken` holding an X.509 certificate, a SAML assertion), a `wsu:Timestamp`, `ds:Signature` elements over chosen parts of the message, and `xenc:EncryptedKey` / `xenc:ReferenceList` elements saying what was encrypted and with which key. A message may carry several Security blocks, but never two aimed at the same recipient, and only one may omit the actor/role. A producer prepends each new child, so the block reads as the steps it took. Sent with `mustUnderstand` true, it obliges a receiver that does not implement WS-Security to fault rather than ignore it.

go deeper

for a junior

Recall that wsse:Security is a SOAP header block, and name what can sit inside it: a token, a timestamp, a signature, an encrypted key.

for a middle

Explain the targeting rules: one block per actor or role, only one untargeted, prepend order, and what mustUnderstand obliges a receiver to do.

for a senior

Show how you would read an unfamiliar Security header in a failing exchange: which node it targets, which token signed what, and which fault code fits.

for a principal

Weigh how much security error detail a service should return to partners, given that WS-Security makes faults optional precisely to deny attackers useful feedback.

## What the header is **WS-Security** (formally *Web Services Security: SOAP Message Security*, an OASIS Standard whose current consolidated text is version **1.1.1**, 2012) adds security to the SOAP message itself rather than to the connection that carries it. Its one structural invention is a SOAP **header block** called `<wsse:Security>`, in the namespace `http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd`. A companion *utility* namespace, prefixed `wsu`, supplies the `wsu:Id` attribute used to point at parts of the message and the `wsu:Timestamp` element. The specification calls the header "a mechanism for attaching security-related information targeted at a specific recipient in the form of a SOAP actor/role". That recipient may be the **ultimate receiver** of the message or an **intermediary** on the way. ## What goes inside The header is deliberately extensible; separate **token profiles** define what each kind of token looks like. The children you meet in practice: | Child | Defined by | Purpose | |---|---|---| | `wsse:UsernameToken` | Username Token Profile | a user name, optionally with a password or password digest | | `wsse:BinarySecurityToken` | core spec plus X.509 Token Profile | a non-XML token, such as an X.509 certificate, Base64-encoded | | a SAML assertion | SAML Token Profile | claims about a subject, issued by an authority | | `wsu:Timestamp` | core spec | `Created` and `Expires` times of the security semantics | | `ds:Signature` | core spec using XML Signature | integrity and origin of chosen elements | | `xenc:EncryptedKey`, `xenc:ReferenceList` | core spec using XML Encryption | the wrapped key and the list of encrypted parts | | `wsse11:SignatureConfirmation` | core spec, 1.1 | in a response, echoes the request's signature value | Tokens are referenced from signatures and encryption through a `wsse:SecurityTokenReference` element, so the key a signature used can be found. ## One header per recipient Because different nodes on a message path may need different security data, the targeting rules are strict: - A message **MAY** carry several `wsse:Security` blocks if they are aimed at separate recipients. - It **MUST NOT** carry two blocks aimed, explicitly or implicitly, at the same recipient, and no two blocks may share an `actor` or `role` value. - Only **one** block may omit the `actor` / `role` attribute. That block **MAY** be processed by anyone but **MUST NOT** be removed before the final destination. - An active intermediary **MAY** add sub-elements to a block aimed at its own node, or add new blocks for other targets. ## Order records the steps taken New sub-elements **SHOULD** be *prepended* to the existing ones, and a signature **MUST** be prepended when it is added. The result is that the header lists the producer's signing and encryption steps in the order a receiver can undo them, with no forward dependency. A key-bearing element, such as a certificate token, **SHOULD** come before the signature that uses it. The specification still leaves the receiver free to process children in whatever order it needs. ```xml <S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="..." xmlns:wsu="..."> <S11:Header> <wsse:Security S11:mustUnderstand="1"> <wsu:Timestamp wsu:Id="TS-1">...</wsu:Timestamp> <wsse:BinarySecurityToken wsu:Id="Cert-1" ValueType="...#X509v3">...</wsse:BinarySecurityToken> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature> </wsse:Security> </S11:Header> <S11:Body wsu:Id="Body-1">...</S11:Body> </S11:Envelope> ``` ## mustUnderstand and errors When the block carries `mustUnderstand` set to true (`"1"` in SOAP 1.1; `"true"` or `"1"` in SOAP 1.2), a receiver **MUST** generate a SOAP fault if it does not implement WS-Security for that namespace, and **MUST** fault if it cannot process the tokens it finds. Unrecognised elements inside the header **SHOULD** cause a fault. The specification defines fault codes in two classes: 1. **Unsupported**: `wsse:UnsupportedSecurityToken`, `wsse:UnsupportedAlgorithm`. 2. **Failure**: `wsse:InvalidSecurity`, `wsse:InvalidSecurityToken`, `wsse:FailedAuthentication`, `wsse:FailedCheck`, `wsse:SecurityTokenUnavailable`, `wsse:MessageExpired`. The tables are written for SOAP 1.1, where the code is the `faultcode`. In SOAP 1.2 the fault's `Code/Value` is `env:Sender` and the WS-Security code goes in `Code/Subcode/Value`. The specification does **not** require a receiver to return a fault at all, because detailed errors can help an attacker; it only says that a failure which *is* returned uses the SOAP Fault mechanism. ## What the header is not - It is not a transport: TLS, if used, still runs underneath, hop by hop. - It does not define a fixed protocol; the specification says it offers building blocks that must be combined carefully, and lists establishing a security context, how trust is established, and non-repudiation among its non-goals. - It does not by itself say which parts must be protected; that is the parties' policy.

  • What fault does a SOAP 1.2 receiver send when a UsernameToken's password does not match?
    If it chooses to report the failure at all (WS-Security does not oblige it to, since a detailed fault can help an attacker), it returns a SOAP 1.2 Fault whose `Code/Value` is `env:Sender` and whose `Code/Subcode/Value` is `wsse:FailedAuthentication`, with a Reason text such as 'The security token could not be authenticated or authorized'. In SOAP 1.1 the same code goes straight into `faultcode`.
  • Can an intermediary add to a wsse:Security header that is already in the message?
    Yes. An active intermediary MAY add sub-elements to an existing `wsse:Security` block if that block is aimed at its own node, or MAY add new Security blocks for other recipients. It prepends what it adds, so the order still records the steps taken. The one block with no actor or role MAY be processed by any node but MUST NOT be removed before the final destination.

saying these in an interview costs you the question

  • WS-Security is a transport layer under SOAP, like TLS.
  • A SOAP message can carry only one wsse:Security header.
  • Two Security headers may target the same role if their tokens differ.
  • The encrypted Body content is moved into the Security header.
  • Every WS-Security failure must be returned to the sender as a detailed fault.
open as a page

In the WS-Security UsernameToken profile, how does PasswordDigest differ from PasswordText, and what stops a captured token from being replayed?

level: middleimportance: must knowfreq 25%

basics

~20 s

PasswordText sends the password, or an equivalent, as is; PasswordDigest sends Base64(SHA-1(nonce + created + password)). Replay is stopped by the receiver, which rejects stale Created times and caches used nonces for that freshness window.

open as a page

Why does a valid WS-Security signature not stop a recorded SOAP message from being replayed, and what does a signed wsu:Timestamp add?

level: middleimportance: should knowfreq 10%

basics

~20 s

A signature proves who produced the bytes and that they are unchanged, so an exact copy verifies again. A signed wsu:Timestamp adds Created and Expires times the receiver can check, bounding how long a copy works and how much history it must remember.

open as a page

In WS-Security, how does a wsse:BinarySecurityToken carry an X.509 certificate, and how does a signature identify the certificate it used?

level: middleimportance: should knowfreq 12%

basics

~20 s

A wsse:BinarySecurityToken carries the Base64-encoded certificate, its ValueType naming the format (#X509v3, #X509PKIPathv1, #PKCS7). The signature's ds:KeyInfo holds a wsse:SecurityTokenReference pointing to that token by ID, or to the certificate by subject key identifier or issuer and serial number.

open as a page

A SOAP 1.2 claim message crosses two intermediaries before its ultimate receiver; how should WS-Security sign and encrypt it so the Body stays protected end to end?

level: seniorimportance: should knowfreq 15%

basics

~20 s

TLS ends at each intermediary, so the sender signs the Body, Timestamp and any header the receiver relies on, and encrypts the Body's content for the ultimate receiver's key, leaving intermediaries only the headers aimed at their own roles.

open as a page

In the WS-Security SAML Token Profile, how do holder-of-key and sender-vouches subject confirmation differ, and what must the receiver verify for each?

level: seniorimportance: nice to knowfreq 7%

basics

~20 s

With holder-of-key, the sender proves it knows a key named in the assertion's subject confirmation, usually by signing message content with it. With sender-vouches, a separate attesting entity the receiver already trusts signs assertion and message together, vouching for the subject.

open as a page