org.systinet.wasp.security.ws
Class SecurityTokenSPI

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

public abstract class SecurityTokenSPI

extends java.lang.Object

Abstract base class for implementation of WS-Security security tokens. This class contains DOM representation of security token (Element). It is never created by WSO2 SOA Enablement Server WS-Security implementation, but it is created by corresponding implementation of SecurityTokenHandlerSPI. The processing of security tokens in WS-Security is described in SecurityTokenHandlerSPI.

If security token is referenced from KeyInfo (used in EncryptedData, EncryptedKey and Signature) then it is asked for one or more following keys:

• Encryption:
  encrypting key is used on sender side to encrypt data or keys
  decrypting key is used on receiver side to decrypt encrypted data or keys
• Signature:
  signing key is used on sender side to sign message
  authenticating key is used on receiver side to authenticate (verify) signature

If security token is not referenced, then it contains a claim (e.g., certificate) which have to be verified on the receiver side.

Since:

4.6

Component:

Security-Providers

Field Summary

static int	PM_GENERATE Constant denotes WS-Security header generation mode in doFinal(int) method (i.e., message send).
static int	PM_RECEIVE Constant denotes WS-Security header processing mode in doFinal(int) method (i.e., message receive).

Constructor Summary

SecurityTokenSPI(org.w3c.dom.Element element, SecurityContext securityContext)
Constructor which initializes instance of security token from given element.

SecurityTokenSPI(SecurityContext securityContext, boolean isExternal)
Constructor which initializes instance of security token from configuration (SecurityTokenConf is passed to the constructor of implementation class or the instance can be initialized in SecurityTokenHandlerSPI implementation).

Method Summary

void	addAnyAttribute(java.lang.String attrName, java.lang.String attrValue) Adds DOM attribute without namespace on the security token element.
void	addAnyAttribute(java.lang.String attrNamespaceURI, java.lang.String attrNamespacePrefix, java.lang.String attrLocalName, java.lang.String attrValue) Adds DOM attribute on the security token element.
void	addAnyElement(org.w3c.dom.Element element) Appends given DOM Element to the security token element children.
org.w3c.dom.Element	addAnyElement(java.lang.String namespaceURI, java.lang.String prefix, java.lang.String localName) Creates and returns DOM Element of given namespace, namespace prefix and local name.
void	addBase64Text(byte[] data) Adds child DOM Textnode to the security token element.
abstract void	doFinal(int mode) Method called as a part of security token processing.
abstract java.security.Key	getAuthenticatingKey() Returns Key for signature authentication represented by security token.
java.lang.String	getBaseLocalName() Returns the local name of the security token element.
java.lang.String	getBaseNamespace() Returns the namespace of the security token element.
byte[]	getBytesFromTextChild() Returns data stored in child DOM Textnode - data are decoded from Base64 encoded content of DOM Textnode.
abstract java.security.Key	getDecryptingKey() Returns Key for decryption represented by security token.
static java.lang.String	getDefaultPrefix(java.lang.String namespace) Returns prefix for given namespace URI.
org.w3c.dom.Document	getDocument() Returns DOM Document of security token element .
org.w3c.dom.Element	getElement() Return DOM Element of security token.
abstract java.security.Key	getEncryptingKey() Returns Key for encryption represented by security token.
abstract byte[]	getKeyIdentifier() Returns value of KeyIdentifier used in SecurityTokenReference/KeyIdentifier.
java.lang.String	getKeyIdentifierValueType() Returns a value, which appears as a value type in the referencing key identifier.
abstract SecurityTokenConf	getReceivedConf() Returns the configuration of security token on the received side.
SecurityContext	getSecurityContext() Returns security context of WS-Security security token processing.
abstract java.security.Key	getSigningKey() Returns Key for signing represented by security token.
abstract java.lang.String	getType() Returns the value type of the security token.
abstract java.lang.String	getValueType() Returns QName of value type (e.g., wsse:X509v3).
java.lang.String	getWsuId() Returns value of wsu:id attribute on the security token element.
boolean	isCurrent() Determine if this token is current.
boolean	isExternal() Returns true if token is configured as ExternalSecurityTokensConf.
ReceivedCredentials	mapUser() Creates received credentials.
void	setUniqueWsuId() Sets wsu:id attribute on the security token element with unique (generated) value.
void	setWsuId(java.lang.String wsuId) Sets wsu:id attribute on the security token element with given value.

Methods inherited from class java.lang.Object

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

Field Detail

PM_GENERATE

public static final int PM_GENERATE

Constant denotes WS-Security header generation mode in doFinal(int) method (i.e., message send).

See Also:

Constant Field Values

PM_RECEIVE

public static final int PM_RECEIVE

Constant denotes WS-Security header processing mode in doFinal(int) method (i.e., message receive).

See Also:

Constant Field Values

Constructor Detail

SecurityTokenSPI

public SecurityTokenSPI(SecurityContext securityContext,
                        boolean isExternal)

Constructor which initializes instance of security token from configuration (SecurityTokenConf is passed to the constructor of implementation class or the instance can be initialized in SecurityTokenHandlerSPI implementation).
During initialization the following properties are created or setup:

• security context
• external flag
• DOM Element
• id is set to an unique value - it can be changed in security token constructor to the value from configuration or other desired value

Parameters:

securityContext - processing context

isExternal - flag marking the token as external or not

See Also:

SecurityContext

SecurityTokenSPI

public SecurityTokenSPI(org.w3c.dom.Element element,
                        SecurityContext securityContext)

Constructor which initializes instance of security token from given element. Implementation class usually parse DOM given by passed Element to build security token and validates it (if it is not valid, then WSSecurityException shall be thrown. This validation can be also done in {@link #doFinal} because of processing, the method is called directly after the creation of the instance.
During initialization the following properties are created or setup:

• {@link #getSecurityContext security context}
• {@link #isExternal external flag} to false (external security token is created from configuration only)
• {@link #getElement DOM Element}

Parameters:

element - DOM Element holding the security token

securityContext - processing context

See Also:

SecurityContext

Method Detail

doFinal

public abstract void doFinal(int mode)
                      throws WSSecurityException

Method called as a part of security token processing. Processing is described in SecurityTokenHandlerSPI.

Parameters:

mode - mode of processing - either PM_GENERATE or PM_RECEIVE

Throws:

WSSecurityException

getElement

public org.w3c.dom.Element getElement()

Return DOM Element of security token.

Initialized in SecurityTokenSPI constructors (SecurityTokenSPI(org.systinet.wasp.security.ws.SecurityContext, boolean), SecurityTokenSPI(org.w3c.dom.Element, org.systinet.wasp.security.ws.SecurityContext)).

Returns:

security token DOM Element

getDocument

public org.w3c.dom.Document getDocument()

Returns DOM Document of security token element .

Returns:

DOM Document of security token

getSecurityContext

public SecurityContext getSecurityContext()

Returns security context of WS-Security security token processing.

Initialized in SecurityTokenSPI constructors (SecurityTokenSPI(org.systinet.wasp.security.ws.SecurityContext, boolean), SecurityTokenSPI(org.w3c.dom.Element, org.systinet.wasp.security.ws.SecurityContext)).

Returns:

returns WS-Security processing context

setUniqueWsuId

public void setUniqueWsuId()

Sets wsu:id attribute on the security token element with unique (generated) value.

setWsuId

public void setWsuId(java.lang.String wsuId)

Sets wsu:id attribute on the security token element with given value.

getWsuId

public java.lang.String getWsuId()

Returns value of wsu:id attribute on the security token element.

Returns:

Returns value of wsu:id or null if does not exist.

getKeyIdentifier

public abstract byte[] getKeyIdentifier()

Returns value of KeyIdentifier used in SecurityTokenReference/KeyIdentifier. If token does not support keyIdentifier reference then it must return null.

Returns:

keyIdentifer or null if token does not support reference via keyIdentifier

getValueType

public abstract java.lang.String getValueType()

Returns QName of value type (e.g., wsse:X509v3). This value used for SecurityTokenReference/KeyIdentifer@valueType. If token does not support valueType, then it have to return null.

Returns:

valueType or null (if token does not support valueType)

addAnyAttribute

public void addAnyAttribute(java.lang.String attrNamespaceURI,
                            java.lang.String attrNamespacePrefix,
                            java.lang.String attrLocalName,
                            java.lang.String attrValue)

Adds DOM attribute on the security token element. If attribute is not in namespace, then both attrNamespaceURI and attrNamespacePrefix must be null or you can use addAnyAttribute(java.lang.String, java.lang.String).

Parameters:

attrNamespaceURI - namespace URI of attribute

attrNamespacePrefix - namespace prefix of attribute

attrLocalName - local name of attribute

attrValue - value of attribute

addAnyAttribute

public void addAnyAttribute(java.lang.String attrName,
                            java.lang.String attrValue)

Adds DOM attribute without namespace on the security token element.

Parameters:

attrName - name of attribute

attrValue - value of attribute

See Also:

addAnyAttribute(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

addAnyElement

public void addAnyElement(org.w3c.dom.Element element)

Appends given DOM Element to the security token element children. After appended element the DOM Textnode with value "\n" is appended.

Parameters:

element - appended DOM Element

addAnyElement

public org.w3c.dom.Element addAnyElement(java.lang.String namespaceURI,
                                         java.lang.String prefix,
                                         java.lang.String localName)

Creates and returns DOM Element of given namespace, namespace prefix and local name. The created element is appened to the security token element children using addAnyElement(org.w3c.dom.Element).

Parameters:

namespaceURI - namespace URI of element

prefix - namespace prefix of element

localName - local name of element

Returns:

returns created (and appended) element

addBase64Text

public void addBase64Text(byte[] data)

Adds child DOM Textnode to the security token element. The node contains Base64 String of given data.

Parameters:

data - byte array of data

See Also:

getBytesFromTextChild()

getBytesFromTextChild

public byte[] getBytesFromTextChild()

Returns data stored in child DOM Textnode - data are decoded from Base64 encoded content of DOM Textnode.

Returns:

returns byte array of data stored in child DOM Textnode

See Also:

addBase64Text(byte[])

getDefaultPrefix

public static java.lang.String getDefaultPrefix(java.lang.String namespace)

Returns prefix for given namespace URI.

Parameters:

namespace - asked namespace URI

Returns:

prefix for given namespace or null if namespace's prefix is not known

getEncryptingKey

public abstract java.security.Key getEncryptingKey()
                                            throws WSSecurityException

Returns Key for encryption represented by security token.

Returns:

key for encryption

Throws:

WSSecurityException - if it is not possible to return the key

See Also:

getDecryptingKey()

getDecryptingKey

public abstract java.security.Key getDecryptingKey()
                                            throws WSSecurityException

Returns Key for decryption represented by security token.

Returns:

key for decryption

Throws:

WSSecurityException - if it is not possible to return the key

See Also:

getEncryptingKey()

getSigningKey

public abstract java.security.Key getSigningKey()
                                         throws WSSecurityException

Returns Key for signing represented by security token.

Returns:

key for signig

Throws:

WSSecurityException - if it is not possible to return the key

See Also:

getAuthenticatingKey()

getAuthenticatingKey

public abstract java.security.Key getAuthenticatingKey()
                                                throws WSSecurityException

Returns Key for signature authentication represented by security token.

Returns:

key for authentication

Throws:

WSSecurityException - if it is not possible to return the key

See Also:

getSigningKey()

getReceivedConf

public abstract SecurityTokenConf getReceivedConf()

Returns the configuration of security token on the received side. If the security token was created from DOM Element by SecurityTokenSPI(org.w3c.dom.Element, org.systinet.wasp.security.ws.SecurityContext) on the receiver side, then this method is called during the processing. Developer must use SecurityContext.getMessageConf() to create the configuration - the security token configuration holder is created using MessageConf.newSecurityToken. The MessageConf object returned by SecurityContext.getMessageConf() must not be altered.

Returns:

configuration of received security token

See Also:

getSecurityContext()

getType

public abstract java.lang.String getType()

Returns the value type of the security token. Read security token processing for details how value type is used.

Returns:

the security token value type

See Also:

Constants.ST_VALUE_TYPE_USERNAME, Constants.ST_VALUE_TYPE_X509V3, Constants.ST_VALUE_TYPE_SYMMETRICKEY

getBaseNamespace

public java.lang.String getBaseNamespace()

Returns the namespace of the security token element.

Returns:

SecurityContext.getWsseNamespace() by default

getBaseLocalName

public java.lang.String getBaseLocalName()

Returns the local name of the security token element.

Returns:

WSSecurity.ELEMENT_BINARY_SECURITY_TOKEN by default.

isExternal

public boolean isExternal()

Returns true if token is configured as ExternalSecurityTokensConf.

Returns:

true if token is configured as ExternalSecurityTokensConf.

getKeyIdentifierValueType

public java.lang.String getKeyIdentifierValueType()

Returns a value, which appears as a value type in the referencing key identifier. Defaults to getValueType().

Returns:

the value type

mapUser

public ReceivedCredentials mapUser()

Creates received credentials. This method is called when incoming message with signed SOAP Body is processed and received credentials has not been set yet. Material used for signing (eg. X.509 certificate, Kerberos ticket) may be used to map principal to local identity.

Returns:

received credentials; null by default

Since:

6.5

isCurrent

public boolean isCurrent()

Determine if this token is current.

Returns:

true (default) if this token is currently current, false otherwise

Since:

6.5