How Token referencing works in WS-Security?

Token referencing means how one token finds the other.

For example digital signature and encryption operations require that a key be specified. For various reasons,the element containing the key in question may be located elsewhere in the message or completely outside the message.

Let's first see an example where the key in question located inside the element it self.

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate> 
MIICPjCCAacCBEngcUswDQYJKoZIhvcNAQEEBQAwZjELMAkGA1UEBhMCTEsxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1NlYXR0bGUxDTALBgNVBAoTBFdTTzIxDTALBgNVBAsTBE5vbmUxEjA
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>

If you take the KeyInfo element out from the above example you'll see - the public key corresponding to the Signature being included inside the Signature element it self.

Let's take another example.

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyInfo>
<wsse:SecurityTokenReference
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:KeyIdentifier
EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" 
ValueType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#ThumbprintSHA1">
NC+OYE+VLHQQCmJL3DVRkUyxrr0=
</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>

Have a look at wsse:SecurityTokenReference element.

Here it contains the thumbprint [http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#ThumbprintSHA1] value of the certificate being used to sign.

In this case - to validate the signature, you need to have the correponding certificate in your key store, at the receipient end.

The wsse:SecurityTokenReference element provides an open content model for referencing key bearing elements because not all of them support a common reference pattern. Similarly, some have closed schemas and define their own reference mechanisms. The open content model allows appropriate reference mechanisms to be used.

If a wsse:SecurityTokenReference is used outside of the security header processing block the meaning of the response and/or processing rules of the resulting references MUST be specified by the the specific profile.

Let's take another example.

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyInfo>
<wsse:SecurityTokenReference 
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:Reference 
URI="#CertId-33F15B961A92D5966C12511059451031" 
ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" />
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>

Here, have a look at wsse:Reference and it's attribute URI. Also notice that the value of URI starts with a '#' - that means, this refers to a token that should be found within the message it self.

In other words - the message should have an element with the wsu:Id CertId-33F15B961A92D5966C12511059451031 [ommiting #].

In our case - the token reffered is included in the message it self as a BinarySecurityToken.

<wsse:BinarySecurityToken
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
wsu:Id="CertId-33F15B961A92D5966C12511059451031">
MIIC0TCCAbkCBEp6Up4wDQYJKoZIhvcNAQEEBQAwLTELMAkGAUEBhMCTEsxDTALBgNVBAsMBHdzbzIxDzANBgNVBAMMBmNsaWVudDAeFw0wOTA4MDYwMzQ4NDZaFw0xMjA4MDUwMzQ4NDZaMC0xCzAJBgNVBAYTAkxLMQ0wCwYDVQQLDAR3c28yMQ8wDQYDVQQDDAZjbGllbnQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCAMXusC<wsse:BinarySecurityToken>

Let's get in to theory a bit.

The following list provides a list of the specific reference mechanisms defined in WSS: SOAP Message Security in preferred order (i.e., most specific to least specific):

• Direct References – This allows references to included tokens using URI fragments and external tokens using full URIs.
• Key Identifiers – This allows tokens to be referenced using an opaque value that represents the token (defined by token type/profile).
• Key Names – This allows tokens to be referenced using a string that matches an identity assertion within the security token. This is a subset match and may result in multiple security tokens that match the specified name.
• Embedded References - This allows tokens to be embedded (as opposed to a pointer to a token that resides elsewhere).

In the samples provided before; the second example is for "Key Identifiers" and the third is for "Direct References".

Now, let's see an example of Embedded References.

<wsse:SecurityTokenReference>
<wsse:Embedded wsu:Id="tok1">
<saml:Assertion xmlns:saml="...">
...
<saml:Assertion>
</wsse:Embedded>
</wsse:SecurityTokenReference>

Following is an example of Key Names.

<ds:KeyInfo Id="..." xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyName>CN=Hiroshi Maruyama, C=JP</ds:KeyName>
</ds:KeyInfo>

It is strongly RECOMMENDED to use wsse:KeyIdentifier elements. However, if Key Names are used, then it is strongly RECOMMENDED that ds:KeyName elements conform to the attribute names in section 2.3 of RFC 2253 (this is recommended by XML Signature for ds:X509SubjectName, for interoperability.