IBM WebSphere Application ServerTM
Release 8

com.ibm.websphere.wssecurity.wssapi.token
Class GenericSecurityTokenFactory

java.lang.Object
  extended by com.ibm.websphere.wssecurity.wssapi.token.GenericSecurityTokenFactory

public abstract class GenericSecurityTokenFactory
extends java.lang.Object

This API is used for the creation of security tokens.

The code snippets that are shown below demonstrate how to use this API to create security tokens:

Sample code for creating a fully-populated UsernameToken
   GenericSecurityTokenFactory gstFactory = GenericSecurityTokenFactory.getInstance();
 
   UsernameToken unt = gstFactory.getFullUsernameToken(username,password);
    
Sample code for creating a custom token
   GenericSecurityTokenFactory gstFactory = GenericSecurityTokenFactory.getInstance();
   
   // 1. Create the valueType
   javax.xml.namespace.QName valueType = new QName("", "http://myToken");
 
   // 2. Get a unique ID
   String uniqueID = gstFactory.createUniqueId();
 
   // 3. Build the custom element
   org.w3c.dom.Element customElement = buildmyTokenElement(uniqueId);
 
   // 4. Create the security token
   GenericSecurityToken myToken = gstFactory.getToken(customElement, valueType);
 
    


Constructor Summary
GenericSecurityTokenFactory()
           
 
Method Summary
abstract  java.lang.String createUniqueId()
          Create a Unique ID that can be put into a custom token so that it can be referred to properly when being individually signed or encrypted.
abstract  SecurityToken getConsumerTokenFromSharedState(java.util.Map sharedState, javax.xml.namespace.QName valueType)
          Get a consumed token from the shared state.
abstract  UsernameToken getFullUsernameToken(java.lang.String username)
          Create a fully-populated UsernameToken with a username and no password.
abstract  UsernameToken getFullUsernameToken(java.lang.String username, char[] password)
          Create a fully-populated UsernameToken with a username and password.
abstract  UsernameToken getFullUsernameToken(java.lang.String username, char[] password, boolean useTimestamp)
          Create a fully-populated UsernameToken with a username, password, and timestamp.
abstract  SecurityToken getGeneratorTokenFromSharedState(java.util.Map sharedState, javax.xml.namespace.QName valueType)
          Get a generated token from the shared state.
static GenericSecurityTokenFactory getInstance()
          Retrieves an instance of the GenericSecurityTokenFactory
abstract  BinarySecurityToken getSimpleBinarySecurityToken(java.lang.Class tokenClass, byte[] binary)
          Create a sparse BinarySecurityToken (no XML) for use with binary security token generators (like LTPA).
abstract  UsernameToken getSimpleUsernameToken(java.lang.String username)
          Create a sparse UsernameToken (no XML) with a username and password to pass to the UNTGenerateLoginModule.
abstract  UsernameToken getSimpleUsernameToken(java.lang.String username, char[] password)
          Create a sparse UsernameToken (no XML) with a username to pass to the UNTGenerateLoginModule.
abstract  X509Token getSimpleX509PrivateToken(java.security.cert.X509Certificate certificate, java.security.Key privateKey)
          Create a sparse X509Token (no XML) that contains a private key.
abstract  X509Token getSimpleX509PublicToken(java.security.cert.X509Certificate certificate)
          Create a sparse X509Token (no XML) that contains just a public certificate.
abstract  X509Token getSimpleX509Token(java.security.cert.X509Certificate certificate, java.security.Key privateKey)
          Create a sparse X509Token (no XML).
abstract  GenericSecurityToken getToken()
          Create an unpupulated GenericSecurityToken.
abstract  GenericSecurityToken getToken(org.w3c.dom.Element element, javax.xml.namespace.QName valueType)
          Create a custom GenericSecurityToken from a org.w3c.dom element
abstract  GenericSecurityToken getToken(java.io.InputStream is, javax.xml.namespace.QName valueType)
          Create a custom GenericSecurityToken from an XML fragment given as a String
abstract  GenericSecurityToken getToken(org.apache.axiom.om.OMElement element, javax.xml.namespace.QName valueType)
          Create a custom GenericSecurityToken from an OMElement
abstract  GenericSecurityToken getToken(com.ibm.wsspi.wssecurity.wssapi.OMStructure xml, javax.xml.namespace.QName valueType)
           
abstract  GenericSecurityToken getToken(java.lang.String xmlFragment, javax.xml.namespace.QName valueType)
          Create a custom GenericSecurityToken from an XML fragment given as a String
abstract  void putAuthenticatedTokenToSharedState(java.util.Map sharedState, SecurityToken token)
          Put a token that has been authenticated by a login module into the shared state.
abstract  void putConsumerTokenToSharedState(java.util.Map sharedState, SecurityToken token)
          Put a consumed token on the shared state.
abstract  void putGeneratorTokenToSharedState(java.util.Map sharedState, SecurityToken token)
          Put a generated token on the shared state.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GenericSecurityTokenFactory

public GenericSecurityTokenFactory()
Method Detail

getInstance

public static GenericSecurityTokenFactory getInstance()
                                               throws WSSException
Retrieves an instance of the GenericSecurityTokenFactory

Returns:
GenericSecurityTokenFactory object
Throws:
WSSException - if the illegal access occurs or if the WSSFactory instance is not generated.

getToken

public abstract GenericSecurityToken getToken(com.ibm.wsspi.wssecurity.wssapi.OMStructure xml,
                                              javax.xml.namespace.QName valueType)

getToken

public abstract GenericSecurityToken getToken()
Create an unpupulated GenericSecurityToken.

Returns:
An Unpopulated GenericSecurityToken

getToken

public abstract GenericSecurityToken getToken(org.apache.axiom.om.OMElement element,
                                              javax.xml.namespace.QName valueType)
Create a custom GenericSecurityToken from an OMElement

Parameters:
element - axiom representation of the custom element
valueType - the token's value type
Returns:
A fully-populated custom GenericSecurityToken

getToken

public abstract GenericSecurityToken getToken(org.w3c.dom.Element element,
                                              javax.xml.namespace.QName valueType)
                                       throws java.lang.Exception
Create a custom GenericSecurityToken from a org.w3c.dom element

Parameters:
element - w3c.dom representation of the custom element
valueType - the token's value type
Returns:
A fully-populated custom GenericSecurityToken
Throws:
java.lang.Exception

getToken

public abstract GenericSecurityToken getToken(java.lang.String xmlFragment,
                                              javax.xml.namespace.QName valueType)
                                       throws java.lang.Exception
Create a custom GenericSecurityToken from an XML fragment given as a String

Parameters:
xmlFragment - token represented as a well-formed XML fragment
valueType - the token's value type
Returns:
A fully-populated custom GenericSecurityToken
Throws:
java.lang.Exception

getToken

public abstract GenericSecurityToken getToken(java.io.InputStream is,
                                              javax.xml.namespace.QName valueType)
                                       throws java.lang.Exception
Create a custom GenericSecurityToken from an XML fragment given as a String

Parameters:
is - an inputStream corresponding to a serialized XML element. The programmer is responsible for closing of the stream accordingly.
valueType - the token's value type
Returns:
A fully-populated custom GenericSecurityToken
Throws:
java.lang.Exception

getFullUsernameToken

public abstract UsernameToken getFullUsernameToken(java.lang.String username)
                                            throws javax.security.auth.login.LoginException
Create a fully-populated UsernameToken with a username and no password.

Parameters:
username - username for the UsernameToken element
Returns:
A fully-populated UsernameToken
Throws:
javax.security.auth.login.LoginException

getFullUsernameToken

public abstract UsernameToken getFullUsernameToken(java.lang.String username,
                                                   char[] password)
                                            throws javax.security.auth.login.LoginException
Create a fully-populated UsernameToken with a username and password.

Parameters:
username - username for the UsernameToken element
password - password for the UsernameToken element
Returns:
A fully-populated UsernameToken
Throws:
javax.security.auth.login.LoginException

getFullUsernameToken

public abstract UsernameToken getFullUsernameToken(java.lang.String username,
                                                   char[] password,
                                                   boolean useTimestamp)
                                            throws javax.security.auth.login.LoginException
Create a fully-populated UsernameToken with a username, password, and timestamp.

Parameters:
username - username for the UsernameToken element
password - password for the UsernameToken element. Null for no password.
useTimestamp - true=add timestamp, false=no timestamp
Returns:
A fully-populated UsernameToken
Throws:
javax.security.auth.login.LoginException

createUniqueId

public abstract java.lang.String createUniqueId()
Create a Unique ID that can be put into a custom token so that it can be referred to properly when being individually signed or encrypted.

Returns:
A Unique ID String

getGeneratorTokenFromSharedState

public abstract SecurityToken getGeneratorTokenFromSharedState(java.util.Map sharedState,
                                                               javax.xml.namespace.QName valueType)
Get a generated token from the shared state.

This method can be used by stacked login modules to retrieve a token of the specified value from the com.ibm.wsspi.wssecurity.core.Constants.WSSECURITY_TOKEN_TO_BE_INSERTED property on the shared state.

Parameters:
sharedState - JAAS login module shared state Map
valueType - Value type of the desired token
Returns:
A SecurityToken of the specified value type

getConsumerTokenFromSharedState

public abstract SecurityToken getConsumerTokenFromSharedState(java.util.Map sharedState,
                                                              javax.xml.namespace.QName valueType)
Get a consumed token from the shared state.

This method can be used by stacked login modules to retrieve a token of the specified value from the com.ibm.wsspi.wssecurity.core.Constants.WSSECURITY_TOKEN_PROCESSED property on the shared state.

Parameters:
sharedState - JAAS login module shared state Map
valueType - Value type of the desired token
Returns:
A SecurityToken of the specified value type

putGeneratorTokenToSharedState

public abstract void putGeneratorTokenToSharedState(java.util.Map sharedState,
                                                    SecurityToken token)
Put a generated token on the shared state.

This method can be used by stacked login modules to put a token in a token list on the com.ibm.wsspi.wssecurity.core.Constants.WSSECURITY_TOKEN_TO_BE_INSERTED property in the shared state.

Parameters:
sharedState - JAAS login module shared state Map
token - Token to insert

putConsumerTokenToSharedState

public abstract void putConsumerTokenToSharedState(java.util.Map sharedState,
                                                   SecurityToken token)
Put a consumed token on the shared state.

This method can be used by stacked login modules to put a token in a token list on the com.ibm.wsspi.wssecurity.core.Constants.WSSECURITY_TOKEN_TO_BE_INSERTED property in the shared state.

Parameters:
sharedState - JAAS login module shared state Map
Token - Token to insert

getSimpleUsernameToken

public abstract UsernameToken getSimpleUsernameToken(java.lang.String username)
Create a sparse UsernameToken (no XML) with a username and password to pass to the UNTGenerateLoginModule.

Parameters:
username - username for the UsernameToken element
password - password for the UsernameToken element. Null for no password.
Returns:
A sparse UsernameToken

getSimpleUsernameToken

public abstract UsernameToken getSimpleUsernameToken(java.lang.String username,
                                                     char[] password)
Create a sparse UsernameToken (no XML) with a username to pass to the UNTGenerateLoginModule.

Parameters:
username - username for the UsernameToken element
Returns:
A sparse UsernameToken

getSimpleX509PublicToken

public abstract X509Token getSimpleX509PublicToken(java.security.cert.X509Certificate certificate)
Create a sparse X509Token (no XML) that contains just a public certificate.

Parameters:
certificate - public certificate for the token
Returns:
A sparse X509Token

getSimpleX509PrivateToken

public abstract X509Token getSimpleX509PrivateToken(java.security.cert.X509Certificate certificate,
                                                    java.security.Key privateKey)
                                             throws WSSException
Create a sparse X509Token (no XML) that contains a private key.

Parameters:
certificate - public certificate for the token (may be null)
privateKey - private key for the token
Returns:
A sparse X509Token
Throws:
WSSException - if the privateKey is null

getSimpleX509Token

public abstract X509Token getSimpleX509Token(java.security.cert.X509Certificate certificate,
                                             java.security.Key privateKey)
Create a sparse X509Token (no XML).

Parameters:
certificate - public certificate for the token (may be null)
privateKey - private key for the token (may be null)
Returns:
A sparse X509Token

getSimpleBinarySecurityToken

public abstract BinarySecurityToken getSimpleBinarySecurityToken(java.lang.Class tokenClass,
                                                                 byte[] binary)
                                                          throws WSSException
Create a sparse BinarySecurityToken (no XML) for use with binary security token generators (like LTPA).

This method is used to obtain sparse BinarySecurityTokens such as LTPAToken.class or LTPAv2Token.class

Parameters:
tokenClass - class name to instantiate for the token
binary - unencoded token bytes for the token
Returns:
A sparse BinarySecurityToken
Throws:
WSSException - if the tokenClass is not a recognized built-in class that extends BinarySecurityToken

putAuthenticatedTokenToSharedState

public abstract void putAuthenticatedTokenToSharedState(java.util.Map sharedState,
                                                        SecurityToken token)
Put a token that has been authenticated by a login module into the shared state.

This method should be used specifically by login modules that are stacked under UNTConsumeLoginModule and a configuration is in place to defer the authentication of the UsernameToken to the stacked login module. The SAME username token that was obtained from the shared state with getConsumerTokenFromSharedState to authenticate must be put back onto the shared state using this method. If the objects do not match, UNTConsumeLoginModule will assume that the token has not be authenticated and will throw a LoginException. With UNTConsumeLoginModule, to defer authentication to a stacked login module, configure the following property in the UsernameToken consumer callback handler:

com.ibm.wsspi.wssecurity.token.UsernameToken.authDeferred=true

Parameters:
sharedState - JAAS login module shared state Map
token - token that has been authenticated

IBM WebSphere Application ServerTM
Release 8