Skip navigation links

oracle.security.xmlsec.wss.username
Class UsernameToken

java.lang.Object
oracle.security.xmlsec.util.XMLNode
oracle.security.xmlsec.util.XMLElement
oracle.security.xmlsec.wss.WSSElement
oracle.security.xmlsec.wss.username.UsernameToken

All Implemented Interfaces:

WSSecurityToken

public class UsernameToken

extends WSSElement

implements WSSecurityToken

Represents a WSS UsernameToken element. Conforms to Username Token Profile 1.1

Creating UsernameTokens.

1) If you want to use clear text passwords

 UsernameToken ut = new UsernameToken(doc);
 ut.setUsername("Zoe");
 ut.setPassword("IloveDogs");
 

2) Whereas if you want to use digested passwords

 SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
 byte nonce[] = new byte[20];
 random.nextBytes(nonce); // compute a 20 byte random nonce
 
 UsernameToken ut = new UsernameToken(doc);
 ut.setUsername("Zoe");
 ut.setNonce(nonce);
 ut.setCreatedDate(new Date()); // Set the date to now
 ut.setPasswordDigest("IloveDogs"); // will compute the digest from this clear text password
 

3) You should not put passwords at all, if you are username tokens for key derivation

 SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
 byte salt[] = new byte[15];
 random.nextBytes(salt); // compute a 15 byte random salt

 UsernameToken ut = new UsernameToken(doc);
 ut.setUsername("Zoe");
 ut.setSalt(1, salt);

 SecretKey key = ut.deriveKey("IloveDogs");
 
 // Use this key for signing or encryption
 

Validating UsernameTokens

  UsernameToken ut = new UsernameToken(utElement);
  String username = ut.getUsername(); // extract the user name
  char expectedPassword[];  // get the expected password for this user
 
  // Check if this a plain text password
  if (ut.getPasswordType().equals(UsernameToken.PASSWORD_TEXT) {
    char password[] = ut.getPassword(); // extract the plain text password
    
    // Check if the password matches
    if (!Arrays.equals(password, expectedPassword)) {
    }
    
  } 
  // Check if this a digested password
  else if (ut.getPasswordType().equals(UsernameToken.PASSWORD_DIGEST) {
    String password = ut.getPasswordDigest(); // extract the digested password
   
    byte nonce[] = ut.getNonce(); // can be null
    Date createdDate = ut.getCreatedDate(); // can be null
   
    // Following is the RECOMMENDED processing from the spec:
    //   if both nonce and createdDate are null reject this token
    //   if createDate is not null, reject if it is stale 
    //         (guideline: older then 5 mins is stale)
    //   if nonce is not null, reject if this nonce has already been used before 
    //         (need to maintain a cache of used nonces)
   
    // After doing the above checks, check if the digested password matches
    if (!isValid(username, expectedPassword)) {
    } 
   
 } 
 

Field Summary

static java.lang.String	PASSWORD_DIGEST Specifies that the type of password is a digest of the password.
static java.lang.String	PASSWORD_TEXT Specifies that the type of password is a plaintext password, derived password or a password hash.

Fields inherited from class oracle.security.xmlsec.util.XMLNode

node, systemId

Constructor Summary

UsernameToken(org.w3c.dom.Document owner)
Create a new UsernameToken instance.

UsernameToken(org.w3c.dom.Element element)
Create a new UsernameToken instance from the given XML element.

UsernameToken(org.w3c.dom.Element element, java.lang.String systemId)
Create a new UsernameToken instance from the given XML element.

Method Summary

static void	addKeyDerivator(KeyDerivator resolver) Deprecated.
static void	addPasswordRetriever(PasswordRetriever resolver) Register a PasswordRetriever instance to lookup the password.
byte[]	computePasswordDigest(byte[] nonce, WSUCreated created, char[] passwd) Creates the SHA-1 digest of the the given password and optionally nonce and/or creation timpstamp.
byte[]	createSecretKey() Deprecated.
byte[]	createSecretKey(char[] passwd) Deprecated.
javax.crypto.SecretKey	deriveKey() Uses the password retriever to get this user's password, and then extracts the salt and iteration from this token and calls deriveKey(char passwd[], byte salt[], int iteration)
javax.crypto.SecretKey	deriveKey(char[] passwd) Extracts the salt and iteration from this token and calls deriveKey(char passwd[], byte salt[], int iteration)
static javax.crypto.SecretKey	deriveKey(char[] passwd, byte[] salt, int iteration) Derive a key from the passwd using the algorithm mentioned in the WSS 1.1 UsernameToken profile.
WSUCreated	getCreated() Returns the token creation timestamp.
java.util.Date	getCreatedDate() Returns the token creation timestamp.
int	getIteration() get the iteration count for derived keys
javax.crypto.SecretKey	getKey() Deprecated.
byte[]	getNonce() Returns the nonce.
char[]	getPassword() Gets the plaintext password (or password equivalent) stored in the Password child element in this structure.
byte[]	getPasswordDigest() Gets the digest of the password stored in the Password child element in this structure.
java.lang.String	getPasswordType() Returns the type of password.
byte[]	getSalt() get the salt for derived keys.
java.lang.Object	getToken() Get the token contents.
oracle.security.xmlsec.util.QName	getTokenName() Returns the token name.
java.lang.String	getUsername() Returns the username value.
boolean	isValid() Checks if the information stored in this token is valid.
boolean	isValid(java.lang.String userName, char[] passwd) Checks if the information stored in this token is valid against the given user name and password pair.
void	setCreated(WSUCreated created) Set the token creation timestamp.
void	setCreatedDate(java.util.Date created) Set the token creation timestamp.
void	setIteration(int iteration) sets the iteration count for derived keys.
void	setNonce(byte[] nonce) Sets the Nonce element with the specified value and the default Base64 encoding.
void	setNonce(byte[] nonce, java.lang.String encType) Sets the Nonce element with the specified value and encoding type of the nonce.
void	setPassword(char[] passwd) Sets the Password element with the plain text text password (or password equivalent) of the user.
void	setPassword(char[] password, java.lang.String passwordType) Sets the Password element.
void	setPasswordDigest(char[] passwd) Computes the password digest, and sets the Password element with the digested password of the user.
void	setSalt(byte[] salt) Set the salt for derived keys Removes any password, nonce and created date in this token
void	setSalt(byte type, byte[] salt) Set the salt for derived keys.
void	setUsername(java.lang.String userName) Sets the username value.

Methods inherited from class oracle.security.xmlsec.wss.WSSElement

getId, getWsuId, setId, setWsuId

Methods inherited from class oracle.security.xmlsec.util.XMLElement

addNSPrefixAttr, addNSPrefixAttr, addNSPrefixAttrDefault, addNSPrefixAttrDefault, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getChildElementsByTagName, getChildElementsByTagName, getChildElementsByTagNameNS, getChildElementsByTagNameNS, getDefaultNSPrefix, getElement, getElementsByTagName, getElementsByTagNameNS, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setDefaultNSPrefix

Methods inherited from class oracle.security.xmlsec.util.XMLNode

appendChild, appendChild, appendTo, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNode, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getSystemId, hasAttributes, hasChildNodes, insertBefore, insertBefore, isSupported, normalize, removeChild, removeChild, replaceChild, replaceChild, setNodeValue, setPrefix, setSystemId, toBytesXML, toStringXML

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.security.xmlsec.wss.WSSecurityToken

getNode

Field Detail

PASSWORD_TEXT

public static final java.lang.String PASSWORD_TEXT

Specifies that the type of password is a plaintext password, derived password or a password hash.

See Also:

Constant Field Values

PASSWORD_DIGEST

public static final java.lang.String PASSWORD_DIGEST

Specifies that the type of password is a digest of the password.

See Also:

Constant Field Values

Constructor Detail

UsernameToken

public UsernameToken(org.w3c.dom.Element element)

Create a new UsernameToken instance from the given XML element.

Parameters:

element - A wsse:UsernameToken element.

UsernameToken

public UsernameToken(org.w3c.dom.Element element,
                     java.lang.String systemId)

Create a new UsernameToken instance from the given XML element.

Parameters:

element - A wsse:UsernameToken element.

systemId - The URI string system ID for this element.

UsernameToken

public UsernameToken(org.w3c.dom.Document owner)

Create a new UsernameToken instance.

Parameters:

owner - A XML Document to be used as the owner document of this structure.

Method Detail

setUsername

public void setUsername(java.lang.String userName)

Sets the username value.

Parameters:

userName - The username string.

getUsername

public java.lang.String getUsername()

Returns the username value.

Returns:

The username string.

setNonce

public void setNonce(byte[] nonce)

Sets the Nonce element with the specified value and the default Base64 encoding.

Parameters:

nonce - The nonce bytes.

setNonce

public void setNonce(byte[] nonce,
                     java.lang.String encType)

Sets the Nonce element with the specified value and encoding type of the nonce.

Parameters:

nonce - The nonce bytes.

encType - The encoding type of the nonce.

getNonce

public byte[] getNonce()

Returns the nonce.

Returns:

The nonce bytes.

setCreatedDate

public void setCreatedDate(java.util.Date created)

Set the token creation timestamp.

Parameters:

created -

setCreated

public void setCreated(WSUCreated created)

Set the token creation timestamp.

Parameters:

created - The creation timestamp.

getCreated

public WSUCreated getCreated()

Returns the token creation timestamp.

Returns:

The creation timestamp.

getCreatedDate

public java.util.Date getCreatedDate()

Returns the token creation timestamp.

Returns:

The creation timestamp.

setPassword

public void setPassword(char[] passwd)

Sets the Password element with the plain text text password (or password equivalent) of the user.

Parameters:

passwd - The clear text password (or password equivalent) of the user.

setPasswordDigest

public void setPasswordDigest(char[] passwd)

Computes the password digest, and sets the Password element with the digested password of the user.

Parameters:

passwd - The clear text password (or password equivalent) of the user.

setPassword

public void setPassword(char[] password,
                        java.lang.String passwordType)

Sets the Password element. The actual value stored in this element depends on the password type provided.

Parameters:

password - The clear text password (or password equivalent) of the user. If the password is null, the PasswordRetriever will be used to lookup the passwd.

passwordType - The value for the Type attribute which specifies the type of password being provided in this token.

getPasswordType

public java.lang.String getPasswordType()

Returns the type of password.

Returns:

The password type URI.

getPassword

public char[] getPassword()

Gets the plaintext password (or password equivalent) stored in the Password child element in this structure. Returns null if PasswordDigest type is used.

Returns:

The raw bytes of the password.

getPasswordDigest

public byte[] getPasswordDigest()

Gets the digest of the password stored in the Password child element in this structure. Returns null if PasswordDigest type is not used.

Returns:

The raw bytes of the digested password.

isValid

public boolean isValid()

Checks if the information stored in this token is valid. Compares the password stored in this token with the password returned by the PasswordRetriever. If the token has a plain text password, compare the password directly. Otherwise if it has a digested password, then compute the digest of the password returned by the password retriever with the nonce and the created date that is present in the token, and then compare the computed digest with the digest present in the token.

Returns:

Returns true if the supplied credentials match the token credentials or false otherwise.

isValid

public boolean isValid(java.lang.String userName,
                       char[] passwd)

Checks if the information stored in this token is valid against the given user name and password pair. If the token has a plain text password, compare the password directly. Otherwise if it has a digested password, then compute the digest of the given plain text password with the nonce and the created date that is present in the token, and then compare the computed digest with the digest present in the token. Does not check if the nonce is being replayed or if the createdTimestamp is stale.

Parameters:

userName - The user name value.

passwd - The password value. If the password is null, the PasswordRetriever will be used to lookup the passwd.

Returns:

Returns true if the supplied credentials match the token credentials or false otherwise.

getSalt

public byte[] getSalt()

get the salt for derived keys. Should be 16 bytes, first byte being 1 for MAC and 2 for encryption

Returns:

the salt bytes or null if there is no salt

setSalt

public void setSalt(byte[] salt)

Set the salt for derived keys Removes any password, nonce and created date in this token

Parameters:

salt - Must be 128 bits - first byte should be 1 for MAC or 2 for Encryption

setSalt

public void setSalt(byte type,
                    byte[] salt)

Set the salt for derived keys. Wrapper over setSalt(byte[] salt);

Parameters:

type - 1 for MAC or 2 for Encryption

salt - Must be 120 bits.

Throws:

java.lang.IllegalArgumentException - is salt is not 120 bits, or type is not 1 or 2

getIteration

public int getIteration()

get the iteration count for derived keys

Returns:

the iteration count or 1000 if nothing is present

setIteration

public void setIteration(int iteration)

sets the iteration count for derived keys. If you don't set this 1000 is assumed

Parameters:

iteration -

createSecretKey

public byte[] createSecretKey()

Deprecated.

Creates a secret key for HMAC signature from this Username token.

Returns:

Returns the secret key bytes or null if the Password child element is not available.

createSecretKey

public byte[] createSecretKey(char[] passwd)

Deprecated.

Creates a secret key for HMAC signature from this Username token.

Parameters:

passwd - The password to use in the secret key generation. If the password is null, the PasswordRetriever will be used to lookup the passwd.

Returns:

Returns the secret key bytes or null.

computePasswordDigest

public byte[] computePasswordDigest(byte[] nonce,
                                    WSUCreated created,
                                    char[] passwd)

Creates the SHA-1 digest of the the given password and optionally nonce and/or creation timpstamp. Password_Digest = Base64 ( SHA-1 ( nonce + created + password ) )

Parameters:

nonce - The nonce bytes.

created - The token creation timestamp

passwd - The password bytes. If the password is null, the PasswordRetriever will be used to lookup the passwd.

Returns:

The computed password digest bytes.

getTokenName

public oracle.security.xmlsec.util.QName getTokenName()

Returns the token name.

Specified by:

getTokenName in interface WSSecurityToken

Returns:

The QName of the token.

getToken

public java.lang.Object getToken()

Get the token contents.

Returns a java.lang.String containing the Username from the Username token.

Specified by:

getToken in interface WSSecurityToken

Returns:

The Username.

getKey

public javax.crypto.SecretKey getKey()
                              throws WSSException

Deprecated.

Get the cryptographic key corresponding to the token contents.

Returns the secret HMAC or Key byte[] derived from the supplied password.

Returns:

The Username.

Throws:

WSSException

addPasswordRetriever

public static void addPasswordRetriever(PasswordRetriever resolver)

Register a PasswordRetriever instance to lookup the password.

Parameters:

resolver - The resolver to use to lookup the password.

addKeyDerivator

public static void addKeyDerivator(KeyDerivator resolver)

Deprecated.

Register a KeyDerivatorResolver instance for use in key identifier resolver operations.

Parameters:

resolver - The resolver to use for key derivation.

deriveKey

public static javax.crypto.SecretKey deriveKey(char[] passwd,
                                               byte[] salt,
                                               int iteration)

Derive a key from the passwd using the algorithm mentioned in the WSS 1.1 UsernameToken profile.

Note: the key derivation mechanisms supported by prior versions of this toolkit are now deprecated

The key is derived as follows. The password (which is UTF-8 encoded) and Salt are concatenated in that order. Only the actual octets of the password are used, it is not padded or zero terminated. This value is hashed using the SHA1 algorithm. The result of this operation is also hashed using SHA1. This process is repeated until the total number of hash operations equals the Iteration count.

In other words: K1 = SHA1( password + Salt)
K2 = SHA1( K1 )
???
Kn = SHA1 ( Kn-1)
Where + means concatenation and n is the iteration count.

The resulting 160 bit value is used in a MAC function or truncated to the appropriate length for encryption

Parameters:

passwd - the password

salt - a 16 byte salt. first byte should be 1 for MAC or 2 for encryption

iteration - the iteration count. should be at least a 1000

Returns:

deriveKey

public javax.crypto.SecretKey deriveKey(char[] passwd)

Extracts the salt and iteration from this token and calls deriveKey(char passwd[], byte salt[], int iteration)

Parameters:

passwd - The user's password, the password retriever is used if null is passed in

Returns:

deriveKey

public javax.crypto.SecretKey deriveKey()

Uses the password retriever to get this user's password, and then extracts the salt and iteration from this token and calls deriveKey(char passwd[], byte salt[], int iteration)

Returns:

Skip navigation links