org.systinet.wasp.security.ws
Class SecurityTokenHandlerSPI

java.lang.Object
  org.systinet.wasp.security.ws.SecurityTokenHandlerSPI

public abstract class SecurityTokenHandlerSPI

extends java.lang.Object

Abstract base class for implementation of WS-Security security token handlers. Implementations of this class handle custom binary security tokens only. Custom binary security token are distinguished by valueType, that indicates token's "value space". Implementation of security token handler handles corresponding implementation of security token.

Security token handler and Security token processing:

• sender side
  Security token configuration is given by SecurityTokenConf configuration interface. The valueType returned by SecurityTokenConf.getType() identifies handler (handler's valueType is given by getLocalValueType(). When handler is choosen, its method createFromConf(SecurityTokenConf,SecurityContext,boolean) is called. Handler has to return instance of corresponding security token from given configuration. From this moment the security token instance is asked for keys. When SecurityTokenSPI.doFinal(int) on the security token instance is called the security token's element is added to the message's security header. After this call the security token is destroyed (no one can further reference it).
• external security tokens on the sender side
  They are created in the same way as security tokens on the sender side and they are informed that they are external (see the last parameter of createFromConf(SecurityTokenConf,SecurityContext,boolean). In next processing there is one exception for external security tokens processing - method SecurityTokenSPI.doFinal(int) is not called - thus security token's element is not added to the message's security header and it is not destroyed (it can be referenced till the end of processing).
• receiver side
  If the incoming message contains wsse:BinarySecurityToken element, then element's ValueType attribute identifies handler. The handler's method createFromXML(Element,SecurityContext) is called. Handler has to return instance of corresponding security token created from given DOM Element. Then methods SecurityTokenSPI.doFinal(int) and SecurityTokenSPI.getReceivedConf() are called on the security token instance - since this point the security token can be asked for keys. The instance of security token exists till the end of the message's security header processing.
• external security tokens on the receiver side
  They are created in the same way as external security tokens on the sender side (i.e., from configuration not from DOM Element). In the next processing (just after creation of security token) the method SecurityTokenSPI.doFinal(int) is called and in contrast to processing of external security token on the sender side, they remain till the end of the message's security header processing.

To add security token handler to the processing, it has to be added to the list of security token handlers:

• Runtime configuration
  User addSecurityTokenHandler(org.systinet.wasp.security.ws.SecurityTokenHandlerSPI) method to add security token handler in runtime.
• Persistent configuration
  See WSSEGlobalConf for details.

Since:

4.6

Component:

Security-Providers

Constructor Summary

SecurityTokenHandlerSPI()

Method Summary

static void	addSecurityTokenHandler(SecurityTokenHandlerSPI securityTokenHandler) This method adds security token handler to the list of security token handlers in the runtime.
abstract SecurityTokenSPI	createFromConf(SecurityTokenConf tokenConf, SecurityContext securityContext, boolean isExternal) Creates a security token from given configuration.
abstract SecurityTokenSPI	createFromXML(org.w3c.dom.Element tokenElement, SecurityContext securityContext) Creates the security token from the given element on the receiver side.
java.lang.String	getLocalElementName() This method is used on the receiver's side to map received element to corresponding security token handler.
abstract java.lang.String	getLocalValueType() Returns local part of the security token valueType handled by the handler.

Methods inherited from class java.lang.Object

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

Constructor Detail

SecurityTokenHandlerSPI

public SecurityTokenHandlerSPI()

Method Detail

getLocalValueType

public abstract java.lang.String getLocalValueType()

Returns local part of the security token valueType handled by the handler. Used on both sender's and receiver's sides.

Returns:

local part of value type QName or URI fragment (e.g., X509v3)

createFromConf

public abstract SecurityTokenSPI createFromConf(SecurityTokenConf tokenConf,
                                                SecurityContext securityContext,
                                                boolean isExternal)
                                         throws WSSecurityException

Creates a security token from given configuration. It also notifies token that it is configured as ExternalSecurityTokensConf. If it is not possible to create security token from given configuration WSSecurityException must be thrown.

Parameters:

tokenConf - the configuration

isExternal - external token flag

Returns:

created instance of security token

Throws:

WSSecurityException - thrown if security token instance cannot be created from the configuration or created security token is invalid

getLocalElementName

public java.lang.String getLocalElementName()

This method is used on the receiver's side to map received element to corresponding security token handler.

Returns:

BinarySecurityToken by default

createFromXML

public abstract SecurityTokenSPI createFromXML(org.w3c.dom.Element tokenElement,
                                               SecurityContext securityContext)
                                        throws WSSecurityException

Creates the security token from the given element on the receiver side. If any problem occures during the creation of security token instance (e.g., untrusted certificate) the WSSecurityException must be thrown.

Parameters:

tokenElement - element, which represents the security token in the XML

Returns:

instance of security token

Throws:

WSSecurityException - thrown if security token instance cannot be created from the element or created security token is invalid

addSecurityTokenHandler

public static void addSecurityTokenHandler(SecurityTokenHandlerSPI securityTokenHandler)

This method adds security token handler to the list of security token handlers in the runtime. This list can be persistently configured in WSSEGlobalConf.setSecurityTokenHandlers.

Parameters:

securityTokenHandler - instance of security token handler