Glossary Item Box

Government Gateway 2.2.0 (MR-01) ISV Developer Help (Doc Version 06/03/08) | Send comments on this topic.

# UsernameToken

The UsernameToken that the Gateway supports is the standard WS-Security UsernameToken; it securely encapsulates the user's User ID and password credential used by the Gateway.

A UsernameToken is used to request from the Security Token Service (STS):

- GatewayTokens which can then be used by the owner to call methods on the SOAP Portal and Public Interfaces For details see Logging on Gateway with a User ID and Password.

An example of a UsernameToken is given below:

    <wsse:UsernameToken
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
      wsu:Id="SecurityToken-08cd6a36-6b9c-4db7-a727-15916cfe19bc">
      <wsse:Username>513FDQ37JILL</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">
        od61xScYr9hAukzvz/DQXAtdxAA=
      </wsse:Password>
      <wsse:Nonce>dL9uL5lBBm6eHwblHY4lVg==</wsse:Nonce>
      <wsu:Created>2004-06-29T09:10:48Z</wsu:Created>
    </wsse:UsernameToken>

#### Username

The User ID that is supplied by the Gateway when the user initially registered (e.g. 513FDQ37JILL) is supplied as the Username.

#### Password

The Type attribute in the Password element means the Gateway requires the password to be passed as a digest.

Calculating the password equivalent

To improve security the Gateway does not normally accept clear text passwords except where an initial or new password is provided, such as at registration or changing a password, where password rules must be checked.

So, before the required digest can be calculated, the following steps must be performed on the clear text password:

1. Lowercase: The Gateway treats passwords as case-insensitive, this means that the password, for example MyPassword1, has to be changed to mypassword1
2. UTF-8: To ensure that all parties are using the same text encoding the password is converted to UTF-8
3. MD5 Hash: An MD5 hash is performed on the UTF-8 encoded value
4. Base64: To convert the hashed password to something that can be sent in text the Base64 representation is taken.

This means that the password MyPassword1 would become DSjkCA3I9k/JYDY5u3qhuQ==

Calculating the password Digest

Once the lowercased hashed password has been obtained, this is then used to generate the password digest value required by the UsernameToken.

To create the digest value, the two additional nodes in the UsernameToken are used:

- Nonce - this is a random value
- Created - this is the timestamp (the Gateway will reject timestamps older than five minutes)

The digest value is calculated as follows: Password_Digest = Base64 (SHA-1 (nonce + created + password equivalent))

That is, concatenate the nonce, creation timestamp, and the password equivalent, digest the combination using the SHA-1 hash algorithm, then Base64 encode the result. This helps obscure the password and offers a basis for preventing replay attacks.

Note:

- The nonce is hashed using the octet (i.e. eight-bit byte) sequence of its decoded value while the timestamp is hashed using the octet sequence of its UTF8 encoding as specified in the contents of the element.
- Further details about how to create the password digest value can be found in the OASIS specification: Web Services Security UsernameToken Profile 1.0

Taking again the example of MyPassword1, the initial steps transformed this into 'DSjkCA3I9k/JYDY5u3qhuQ== '. This in turn would become 'od61xScYr9hAukzvz/DQXAtdxAA=t'.

© Crown Copyright 2008. All rights reserved