org.systinet.wasp.security.ws
Class MessageSecurity

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

public class MessageSecurity

extends java.lang.Object

Manages high-level WS-Security runtime configuration at both context and call scope.

There are several security elements which allows you to compose message security: tokens, signatures and encrypted data. The order in which you add security elements to configuration determines the order of their processing.

Security configuration scope

Context scope WS-Security configuration is shared across all invocations in the same context. To set up context WS-Security configuration, use setContextSecurity(ServiceClient) or setContextSecurity(ServiceEndpoint) method. Before calling these methods, you may need or want to:

• add external tokens

For a message with encrypted data part(s), tokens suitable for decryption have to be available upon the message reception, either in the message itself, or in the receiver's context. Usually, message does not have tokens used for encryption attached, it only referes to them. For data encrypted with the receiver's public key, instance of X509Token is needed, for data encrypted with shared secret key, instance of SharedSecretToken is needed. Use addExternalToken(SecurityToken) method to add a token to external context tokens. See X509Token and SharedSecretToken for examples.
• add tokens, signatures and encrypted data configurations
• adjust validation behaviour

For example to allow acceptance of Username tokens without Nonce and Created subelements (see setAcceptUsernameTokenWithoutNonceAndCreated() method).
• set message properties

For example to add Timestamp header to outgoing messages (see setCreateTimestampHeader() method).
• plug-in custom validator implementation

Call scope WS-Security configuration is valid only for the next call. To set up call WS-Security configuration, use setCallSecurity(ServiceClient) or setCallSecurity(ServiceEndpoint) method. Before calling these methods, you may want to:

• add tokens, signatures and encrypted data configurations
• set message properties

For example add Timestamp header to outgoing message (see setCreateTimestampHeader() method).

Please note that once setContextSecurity or setCallSecurity method is called, further security configuration using the same MessageSecurity instance is not possible and IllegalStateException will be thrown.

Response encryption using requestor's public key

In many situations, you may want to encrypt the response for the requestor using its public key. For such scenario, X509Token may be instantiated with received credentials (see X509Token.X509Token(java.lang.String)), provided that WSO2 SOA Enablement Server successfuly authenticated the requestor. At present, WSO2 SOA Enablement Server attempts to authenticates the requestor only when incoming message contains username token or when the message body is signed.

But there are situations when the requestor signs only a part of the message or does not attach username token to the message, but requires the response encrypted with its public key. For such situations, it is possible to write simple validator (which implements IncomingValidator interface) and add it to the context configuration. In the validator's IncomingValidator.validate(MessageConf) method, incoming message security configuration may be analysed and suitable token selected, and the requestor authenticated using the selected token data. Later on, token with received credentials for response encryption may be instantiated and used.

Since:

4.6

See Also:

UsernameToken, X509Token, SharedSecretToken, Signature, EncryptedData

Component:

Security-Providers

Nested Class Summary

static class

MessageSecurity.Version WS-Security version enumeration.

Constructor Summary

MessageSecurity()
Creates a new MessageSecurity instance.

MessageSecurity(MessageSecurity.Version version)
Creates a new MessageSecurity instance with the specified version.

Method Summary

void	addExternalToken(SecurityToken token) Adds external (context) token to configuration.
void	addSecurityElement(SecurityElement securityElement) Adds a security element to configuration.
void	addToken(SecurityToken token) Adds a token to configuration.
void	setAcceptUsernameTokenWithoutNonceAndCreated() Disables Nonce and Created username token subelements checking (context-scope setting).
void	setCallSecurity(ServiceClient serviceClient) Sets message configuration for the current call.
void	setCallSecurity(ServiceEndpoint serviceEndpoint) Sets message configuration for the current call.
void	setContextSecurity(ServiceClient serviceClient) Sets service client context security configuration.
void	setContextSecurity(ServiceEndpoint serviceEndpoint) Sets service endpoint context security configuration.
void	setCreateTimestampHeader() wsu:Timestamp header will be created.
void	setIgnoreTimestampHeaderExpiration() Disables wsu:Timestamp expiration check (context-scope setting).
void	setSecureFault() Sets a flag to apply security to faults as well.
void	setSecurity(ServiceClient serviceClient) Sets client security configuration.
void	setSecurity(ServiceEndpoint serviceEndpoint) Sets endpoint security configuration.
void	setTimestampHeaderExpiration(int millis) Overrides default timestamp header expiration.
void	setTimestampHeaderMaxAge(int millis) Overrides default timestamp header max age accepted.
void	setTimestampId(java.lang.String id) Sets ID of the timestamp header so it can be referenced using UriReference.
void	setValidator(IncomingValidator validator) Sets incoming validator.
void	setWsseNamespace(java.lang.String wsseNamespace) Deprecated. Use #MessageSecurity(Version) to specify version of WS-Security.
void	setWsuNamespace(java.lang.String wsuNamespace) Deprecated. Use #MessageSecurity(Version) to specify version of WS-Security.

Methods inherited from class java.lang.Object

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

Constructor Detail

MessageSecurity

public MessageSecurity()

Creates a new MessageSecurity instance.

MessageSecurity

public MessageSecurity(MessageSecurity.Version version)

Creates a new MessageSecurity instance with the specified version.

Parameters:

version -

Since:

6.5

Method Detail

addToken

public void addToken(SecurityToken token)

Adds a token to configuration.

Parameters:

token - security token

addExternalToken

public void addExternalToken(SecurityToken token)

Adds external (context) token to configuration. These tokens are needed for incoming messages processing where tokens referenced by security elements in the message are not attached to it. Typical example of such scenario is encryption using X509 or symmetric key token - callee needs to have the token(s) in its context security configuration for successful processing.

Use only for context-scope configuration.

Parameters:

token - context security token

addSecurityElement

public void addSecurityElement(SecurityElement securityElement)

Adds a security element to configuration.

Parameters:

securityElement - security element

setSecureFault

public void setSecureFault()

Sets a flag to apply security to faults as well.

Since:

6.5

setAcceptUsernameTokenWithoutNonceAndCreated

public void setAcceptUsernameTokenWithoutNonceAndCreated()

Disables Nonce and Created username token subelements checking (context-scope setting).

setCreateTimestampHeader

public void setCreateTimestampHeader()

wsu:Timestamp header will be created.

See Also:

setTimestampId(String)

setTimestampId

public void setTimestampId(java.lang.String id)

Sets ID of the timestamp header so it can be referenced using UriReference.

See Also:

setCreateTimestampHeader()

setTimestampHeaderExpiration

public void setTimestampHeaderExpiration(int millis)

Overrides default timestamp header expiration.

Parameters:

millis - expire time

See Also:

WSSEConf.setTimestampHeaderExpiration(Integer)

setTimestampHeaderMaxAge

public void setTimestampHeaderMaxAge(int millis)

Overrides default timestamp header max age accepted.

Parameters:

millis - max age time; -1 for no limit

See Also:

WSSEConf.setTimestampHeaderMaxAge(Integer)

setIgnoreTimestampHeaderExpiration

public void setIgnoreTimestampHeaderExpiration()

Disables wsu:Timestamp expiration check (context-scope setting).

See Also:

WSSEConf.setIgnoreTimestampHeaderExpiration(Boolean)

setSecurity

public void setSecurity(ServiceClient serviceClient)

Sets client security configuration. Same as setContextSecurity(ServiceClient serviceClient).

Parameters:

serviceClient - service client

Since:

6.5

setSecurity

public void setSecurity(ServiceEndpoint serviceEndpoint)

Sets endpoint security configuration. Same as setContextSecurity(ServiceEndpoint serviceEndpoint).

Parameters:

serviceEndpoint - service endpoint

Since:

6.5

setContextSecurity

public void setContextSecurity(ServiceClient serviceClient)

Sets service client context security configuration. It is shared across all calls in the same context.

Parameters:

serviceClient - instance of ServiceClient

setCallSecurity

public void setCallSecurity(ServiceClient serviceClient)

Sets message configuration for the current call.

Parameters:

serviceClient - instance of ServiceClient

setContextSecurity

public void setContextSecurity(ServiceEndpoint serviceEndpoint)

Sets service endpoint context security configuration. It is shared across call in the same context.

Parameters:

serviceEndpoint - instance of ServiceEndpoint

setCallSecurity

public void setCallSecurity(ServiceEndpoint serviceEndpoint)

Sets message configuration for the current call.

Parameters:

serviceEndpoint - instance of ServiceEndpoint

setValidator

public void setValidator(IncomingValidator validator)

Sets incoming validator. See IncomingValidator for more.

Parameters:

validator - validator

setWsseNamespace

public void setWsseNamespace(java.lang.String wsseNamespace)

Deprecated. Use #MessageSecurity(Version) to specify version of WS-Security.

Sets wsse namespace. If not set, default value is used.

Parameters:

wsseNamespace - wsse namespace

See Also:

Constants.DEFAULT_WSSE_NAMESPACE

setWsuNamespace

public void setWsuNamespace(java.lang.String wsuNamespace)

Deprecated. Use #MessageSecurity(Version) to specify version of WS-Security.

Sets wsu namespace. If not set, default value is used.

Parameters:

wsuNamespace - wsu namespace

See Also:

Constants.DEFAULT_WSU_NAMESPACE