IBM WebSphere Application ServerTM
Release 7

com.ibm.websphere.wssecurity.wssapi
Class WSSUtilFactory

java.lang.Object
  extended by com.ibm.websphere.wssecurity.wssapi.WSSUtilFactory

public abstract class WSSUtilFactory
extends java.lang.Object

This API is used for general Web Services Security utility methods for use in JAAS login modules


Constructor Summary
WSSUtilFactory()
           
 
Method Summary
abstract  byte[] decode(byte[] data)
          Decode Base64 encoded data.
abstract  byte[] decode(java.lang.String data)
          Decode Base64 encoded data.
abstract  java.lang.String digestPassword(byte[] nonce, java.util.Date created, char[] password)
          Calculates a password digest string.
abstract  java.lang.String digestPassword(java.lang.String nonce, java.lang.String created, char[] password)
          Calculates a password digest string.
abstract  java.lang.String encode(byte[] data)
          Base64 encode data.
abstract  java.util.Map getCallbackHandlerProperties(javax.security.auth.callback.CallbackHandler handler)
          Get the property map from the callback handler.
abstract  java.util.Map getCallbackHandlerProperties(java.util.Map wssContext)
          Get the property map from the callback handler.
abstract  java.util.List getConsumedTokens(java.util.Map WSSContext)
          Gets the list of consumed tokens.
abstract  org.w3c.dom.Element getDOMProcessingElement(java.util.Map wssContext)
          Get the org.w3c.dom based SOAP processing element object.
abstract  java.util.Map getHTTPRequestHeaders(javax.security.auth.callback.CallbackHandler handler)
          Get the HTTP headers from an inbound SOAP request.
abstract  java.util.Map getHTTPRequestHeaders(java.util.Map wssContext)
          Get the HTTP headers from an inbound SOAP request.
abstract  java.util.Map getHTTPRequestHeaders(org.apache.axis2.context.MessageContext msgContext)
          Get the HTTP headers from an inbound SOAP request.
static WSSUtilFactory getInstance()
          Retrieves an instance of the WSSUtilFactory.
abstract  java.security.KeyStore getKeyStore(java.lang.String keyStoreRef)
          Open a key store.
abstract  java.security.KeyStore getKeyStore(java.lang.String storeType, java.lang.String storePath, char[] storePass)
          Open a key store.
abstract  org.apache.axis2.context.MessageContext getMessageContext(javax.security.auth.callback.CallbackHandler handler)
          Get the MessageContext associated with the current request/response.
abstract  org.apache.axis2.context.MessageContext getMessageContext(java.util.Map wssContext)
          Get the MessageContext associated with the current request/response.
abstract  org.apache.axiom.om.OMElement getProcessingElement(java.util.Map wssContext)
          Get the AXIOM based SOAP processing element object.
abstract  com.ibm.wsspi.wssecurity.core.config.TokenConsumerConfig getTokenConsumerConfig(java.util.Map WSSContext)
          Gets the token consumer configuration object.
abstract  com.ibm.wsspi.wssecurity.core.config.TokenGeneratorConfig getTokenGeneratorConfig(java.util.Map WSSContext)
          Gets the token generator configuration object.
abstract  java.util.Map getWSSContext(javax.security.auth.callback.CallbackHandler handler)
          Get the web services security context map.
abstract  boolean isServiceProvider()
          Identifies if the current application is a web services provider.
abstract  void setConsumedToken(java.util.Map WSSContext, java.util.List tokens)
          Sets a list consumed tokens.
abstract  void setConsumedToken(java.util.Map WSSContext, SecurityToken token)
          Sets a consumed token.
abstract  void setGeneratedToken(java.util.Map WSSContext, java.util.List tokens)
          Sets a list of generated tokens.
abstract  void setGeneratedToken(java.util.Map WSSContext, SecurityToken token)
          Sets a generated token.
abstract  boolean verifyDigestedPassword(UsernameToken unt, char[] expectedPassword)
          Verifies a digested password on a UsernameToken object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WSSUtilFactory

public WSSUtilFactory()
Method Detail

getInstance

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

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

encode

public abstract java.lang.String encode(byte[] data)
Base64 encode data.

Parameters:
data - bytes to be encoded
Returns:
base64 representation of specified byte array.

decode

public abstract byte[] decode(java.lang.String data)
Decode Base64 encoded data.

Parameters:
data - base64 encoded string
Returns:
decoded bytes

decode

public abstract byte[] decode(byte[] data)
Decode Base64 encoded data.

Parameters:
data - base64 encoded bytes
Returns:
decoded bytes

getKeyStore

public abstract java.security.KeyStore getKeyStore(java.lang.String keyStoreRef)
                                            throws WSSException
Open a key store.

Parameters:
keyStoreRef - centralized keystore representation
Returns:
KeyStore object for use with apis
Throws:
WSSException

getKeyStore

public abstract java.security.KeyStore getKeyStore(java.lang.String storeType,
                                                   java.lang.String storePath,
                                                   char[] storePass)
                                            throws WSSException
Open a key store.

Parameters:
storeType - key store type (type that Java security supports, ex jks, jceks, etc)
storePath - path to key store (fully-qualified path name, or URI representation)
storePass - key store password
Returns:
KeyStore object for use with apis
Throws:
WSSException - if the key store cannot be obtained

getHTTPRequestHeaders

public abstract java.util.Map getHTTPRequestHeaders(org.apache.axis2.context.MessageContext msgContext)
Get the HTTP headers from an inbound SOAP request.

This api is intended to be used within a custom login module

Parameters:
msgContext - message context
Returns:
map of HTTP headers from the inbound request
Throws:
WSSException - if the key store cannot be obtained

getHTTPRequestHeaders

public abstract java.util.Map getHTTPRequestHeaders(java.util.Map wssContext)
Get the HTTP headers from an inbound SOAP request.

This api is intended to be used within a custom login module

Parameters:
wssContext - web services security context
Returns:
map of HTTP headers from the inbound request

getHTTPRequestHeaders

public abstract java.util.Map getHTTPRequestHeaders(javax.security.auth.callback.CallbackHandler handler)
                                             throws WSSException
Get the HTTP headers from an inbound SOAP request.

This api is intended to be used within a custom login module

Parameters:
handler - login module's callback handler
Returns:
map of HTTP headers from the inbound request
Throws:
WSSException - if the use of the handler fails

getWSSContext

public abstract java.util.Map getWSSContext(javax.security.auth.callback.CallbackHandler handler)
                                     throws WSSException
Get the web services security context map.

Parameters:
handler - login module's callback handler
Returns:
web services security context map
Throws:
WSSException - if the use of the handler fails

getMessageContext

public abstract org.apache.axis2.context.MessageContext getMessageContext(java.util.Map wssContext)
Get the MessageContext associated with the current request/response.

Parameters:
wssContext - web services security context map
Returns:
MessageContext associated with the current request/response

getMessageContext

public abstract org.apache.axis2.context.MessageContext getMessageContext(javax.security.auth.callback.CallbackHandler handler)
                                                                   throws WSSException
Get the MessageContext associated with the current request/response.

Parameters:
handler - login module's callback handler
Returns:
MessageContext associated with the current request/response
Throws:
WSSException - if the use of the handler fails

getCallbackHandlerProperties

public abstract java.util.Map getCallbackHandlerProperties(java.util.Map wssContext)
Get the property map from the callback handler.

This api can be used to get custom properties from the currently configured callback handler without having to know what the callback handler is

Parameters:
wssContext - web services security context map
Returns:
property map from the currently configured callback handler

getCallbackHandlerProperties

public abstract java.util.Map getCallbackHandlerProperties(javax.security.auth.callback.CallbackHandler handler)
                                                    throws WSSException
Get the property map from the callback handler.

This api can be used to get custom properties from the currently configured callback handler without having to know what the callback handler is.

Parameters:
handler - login module's callback handler
Returns:
property map from the currently configured callback handler
Throws:
WSSException - if the use of the handler fails

getProcessingElement

public abstract org.apache.axiom.om.OMElement getProcessingElement(java.util.Map wssContext)
Get the AXIOM based SOAP processing element object.

This is the target token object for consumers and the parent for generators.

Parameters:
wssContext - web services security context map
Returns:
AXIOM SOAP processing element

getDOMProcessingElement

public abstract org.w3c.dom.Element getDOMProcessingElement(java.util.Map wssContext)
Get the org.w3c.dom based SOAP processing element object.

This is the target token object for consumers and the parent for generators. This method will only return an non-null object if com.ibm.wsspi.wssecurity.domElementEnabled=true is set in the token consumer/generator custom properties (NOT callback handler)

Parameters:
wssContext - web services security context map
Returns:
org.w3c.dom.Element processing element

setConsumedToken

public abstract void setConsumedToken(java.util.Map WSSContext,
                                      SecurityToken token)
Sets a consumed token.

The token is put in the web services security context map and added to the SecurityTokenManager. This method is intended for use by a standalone token consumer login modules and not a login module that is stacked under a built-in token consumer. In the stacked scenario, the built-in consumer will do this work.

Parameters:
wssContext - web services security context map
token - token that was consumed

setConsumedToken

public abstract void setConsumedToken(java.util.Map WSSContext,
                                      java.util.List tokens)
Sets a list consumed tokens.

The tokens are put in the web services security context map and are added to the SecurityTokenManager. This method is intended for use by a standalone token consumer login modules and not a login module that is stacked under a built-in token consumer. In the stacked scenario, the built-in consumer will do this work.

Parameters:
wssContext - web services security context map
tokens - list of tokens that were consumed

setGeneratedToken

public abstract void setGeneratedToken(java.util.Map WSSContext,
                                       SecurityToken token)
Sets a generated token.

The token is put in the web services security context map and added to the SecurityTokenManager. This method is intended for use by a standalone token generator login modules and not a login module that is stacked over a built-in token generator. In the stacked scenario, the built-in generator will do this work.

Parameters:
wssContext - web services security context map
token - token that is to be generated

setGeneratedToken

public abstract void setGeneratedToken(java.util.Map WSSContext,
                                       java.util.List tokens)
Sets a list of generated tokens.

The tokens are put in the web services security context map and are added to the SecurityTokenManager. This method is intended for use by a standalone token generator login modules and not a login module that is stacked over a built-in token generator. In the stacked scenario, the built-in generator will do this work.

Parameters:
wssContext - web services security context map
tokens - list of tokens that are to be

getConsumedTokens

public abstract java.util.List getConsumedTokens(java.util.Map WSSContext)
Gets the list of consumed tokens.

This method retrieves the list of tokens that have been consumed so far in current JAAS config stack.

Parameters:
wssContext - web services security context map
Returns:
List of SecurityToken

getTokenConsumerConfig

public abstract com.ibm.wsspi.wssecurity.core.config.TokenConsumerConfig getTokenConsumerConfig(java.util.Map WSSContext)
Gets the token consumer configuration object.

This method retrieves the token consumer configuration object for the active token consumer.

Parameters:
wssContext - web services security context map
Returns:
token consumer configuration

getTokenGeneratorConfig

public abstract com.ibm.wsspi.wssecurity.core.config.TokenGeneratorConfig getTokenGeneratorConfig(java.util.Map WSSContext)
Gets the token generator configuration object.

This method retrieves the token generator configuration object for the active token generator.

Parameters:
wssContext - web services security context map
Returns:
token generator configuration

isServiceProvider

public abstract boolean isServiceProvider()
                                   throws com.ibm.wsspi.wssecurity.core.SoapSecurityException
Identifies if the current application is a web services provider.

This method determines if the current application is a web services provider or a web services client.

Returns:
true if a service provider, false if a client
Throws:
com.ibm.wsspi.wssecurity.core.SoapSecurityException

digestPassword

public abstract java.lang.String digestPassword(byte[] nonce,
                                                java.util.Date created,
                                                char[] password)
                                         throws javax.security.auth.login.LoginException
Calculates a password digest string.

This method calculates a password digest string that can be used with the UsernameToken #PasswordDigest Password Type

Parameters:
nonce - UsernameToken nonce value in bytes
created - UsernameToken created date
Returns:
the password digest string calculated from the input values
Throws:
javax.security.auth.login.LoginException

digestPassword

public abstract java.lang.String digestPassword(java.lang.String nonce,
                                                java.lang.String created,
                                                char[] password)
                                         throws javax.security.auth.login.LoginException
Calculates a password digest string.

This method calculates a password digest string that can be used with the UsernameToken #PasswordDigest Password Type

Parameters:
nonce - UsernameToken nonce value, base-64 encoded
created - UsernameToken created date in UTC String format (as it appears in the token XNL)
Returns:
the password digest string calculated from the input values
Throws:
javax.security.auth.login.LoginException

verifyDigestedPassword

public abstract boolean verifyDigestedPassword(UsernameToken unt,
                                               char[] expectedPassword)
                                        throws javax.security.auth.login.LoginException
Verifies a digested password on a UsernameToken object.

This method will verify that the comparison password is the same as the password used to make the digested password on the UsernameToken object. This is done by calculating the digest value for the comparison password using the nonce and created data in the token, then comparing it to the digested password on the UsernameToken.

This method can only be used with UsernameTokens that have been consumed by a token consumer (UNTConsumeLoginModule or GenericIssuedTokenConsumeLoginModule). If a UsernameToken was created with a GenericSecurityTokenFactory.getFullUsernameToken method, the password in the token object (not the XML) will be in clear text regardless of the password digest setting. In this case, this method will return false unless both passwords are empty.

Parameters:
unt - UsernameToken containing a digested password
expectedPassword - Password to compare
Returns:
true if the digested value of the comparison password equals the password on the unt object, otherwise false
Throws:
javax.security.auth.login.LoginException

IBM WebSphere Application ServerTM
Release 7