October 29, 2003

UsernameToken Key Generation

We keep getting asked about how key generation works for the UsernameToken in WSE. The algorithm that is used for WSE 2.0 is documented in the WS-Trust specification:

P_SHA1 (password, label + nonce + created)

Where:

  • Password is either the real password or a password equivalent (for example the hash of the real password) represented as a UTF-8 string
  • Label is a shared string between sender and receiver, also a UTF-8 string. For the WSE 2.0 Tech Preview, this is the string "WS-Security". For the final 2.0 release, we'll be looking at making it possible for an application to specify the Label value to be used
  • Nonce is "Number Once" material, a random sequence of bytes generated from a Cryptographic Random Number Generator (RNG), encoded as Base64
  • Created is the created time for the token specified in Zulu time using xsd:DateTime format, again encoded as a UTF-8 string

WSE 2.0 Tech Preview generates key material using this algorithm that is then used to key the HMACSHA1 algorithm used to sign the message. By default, we generate 16 bytes of key material. This is another area where we may introduce more application control for the 2.0 release.

Also of note for those attempting to reproduce this process is a bug in the Tech Preview where the label is taken as ASCII bytes instead of UTF-8.

Now a caveat: UsernameToken has never been the subject of an interoperability test and so we cannot say whether other implementations that have this capability use the same algorithm.

And a few words of caution: I want to urge people to be cautious in their use of the UsernameToken. The model we want to encourage for 2.0 release is that this token is immediately exchanged for a different token, either a customer-specific identity token or a SecurityContextToken (SCT) that then uses derived key tokens for signing and encrypting.

And finally, yes, I know that the Tech Preview doesn't let you use a UsernameToken as part of a WS-Trust RST/RSTR sequence. More on the reasons for that in another post...

Posted by herveyw at October 29, 2003 12:01 AM
Comments

Thanks a lot :)

The label isn't specified in WS-Trust but I would eventually found it (since it's defined as "WS-SecureConversation" in WS-SC spec).

However I may never have found out about the ASCII/UTF8 swap.

May I assume that WSE1 has a similar behaviour ?

Posted by: Sebastien Pouliot at October 29, 2003 09:14 AM

The label for WS-SecureConversation is different because it's context is generating keys for DerivedKeyTokens, not UsernameTokens.

WSE 1.0 does not use the same algorithm; WS-Trust wasn't ready at the time we locked down. Stick with WSE 2.0 for interoperability with this feature.

Posted by: herveyw at October 29, 2003 12:34 PM

I'm not able to revalidate a .NET signature using a HMAC key derivation from Username Tokens. Here's a line from your post which is unclear:


"Also of note for those attempting to reproduce this process is a bug in the Tech Preview where the label is taken as ASCII bytes instead of UTF-8"


The label is "WS-Security". What difference is there between it's UTF-8 representation and its ASCII representation ? My understanding is that ASCII is a subset of UTF-8 and since the string is already in ASCII, it's already in UTF-8.

The token specified in Zulu time using xsd:DateTime format is similarly an ASCII string. Why do you warn us to put it in UTF-8 format?

Clearly, you see some difference. Could you please explain it?



Posted by: Sundeep at February 9, 2004 06:40 PM