Spring Web Services Framework

org.springframework.ws.soap.security.wss4j
Class Wss4jSecurityInterceptor

java.lang.Object
  extended by org.springframework.ws.soap.security.AbstractWsSecurityInterceptor
      extended by org.springframework.ws.soap.security.wss4j.Wss4jSecurityInterceptor
All Implemented Interfaces:
InitializingBean, ClientInterceptor, EndpointInterceptor, SoapEndpointInterceptor

public class Wss4jSecurityInterceptor
extends AbstractWsSecurityInterceptor
implements InitializingBean

A WS-Security endpoint interceptor based on Apache's WSS4J. This inteceptor supports messages created by the AxiomSoapMessageFactory and the SaajSoapMessageFactory.

The validation and securement actions executed by this interceptor are configured via validationActions and securementActions properties, respectively. Actions should be passed as a space-separated strings.

Valid validation actions are:

Validation actionDescription
UsernameTokenValidates username token
TimestampValidates the timestamp
EncryptDecrypts the message
SignatureValidates the signature
NoSecurityNo action performed

Securement actions are:

Securement actionDescription
UsernameTokenAdds a username token
UsernameTokenSignatureAdds a username token and a signature username token secret key
TimestampAdds a timestamp
EncryptEncrypts the response
SignatureSigns the response
NoSecurityNo action performed

The order of the actions that the client performed to secure the messages is significant and is enforced by the interceptor.

Since:
1.5.0
Author:
Tareq Abed Rabbo, Arjen Poutsma
See Also:
Apache WSS4J

Field Summary
static String SECUREMENT_USER_PROPERTY_NAME
           
 
Fields inherited from class org.springframework.ws.soap.security.AbstractWsSecurityInterceptor
logger, WS_SECURITY_NAME
 
Constructor Summary
Wss4jSecurityInterceptor()
           
 
Method Summary
 void afterPropertiesSet()
           
protected  void checkResults(Vector results, Vector validationActionsVector)
          Checks whether the received headers match the configured validation actions.
protected  void cleanUp()
           
protected  void secureMessage(SoapMessage soapMessage, MessageContext messageContext)
          Abstract template method.
 void setEnableSignatureConfirmation(boolean enableSignatureConfirmation)
          Whether to enable signatureConfirmation or not.
 void setSecurementActions(String securementActions)
           
 void setSecurementActor(String securementActor)
          The actor name of the wsse:Security header.
 void setSecurementCallbackHandler(CallbackHandler securementCallbackHandler)
          Sets the WSPasswordCallback handler to use when securing messages.
 void setSecurementCallbackHandlers(CallbackHandler[] securementCallbackHandler)
          Sets the WSPasswordCallback handlers to use when securing messages.
 void setSecurementEncryptionCrypto(Crypto securementEncryptionCrypto)
           
 void setSecurementEncryptionEmbeddedKeyName(String securementEncryptionEmbeddedKeyName)
          Sets the key name that needs to be sent for encryption.
 void setSecurementEncryptionKeyIdentifier(String securementEncryptionKeyIdentifier)
          Defines which key identifier type to use.
 void setSecurementEncryptionKeyTransportAlgorithm(String securementEncryptionKeyTransportAlgorithm)
          Defines which algorithm to use to encrypt the generated symmetric key.
 void setSecurementEncryptionParts(String securementEncryptionParts)
          Property to define which parts of the request shall be encrypted.
 void setSecurementEncryptionSymAlgorithm(String securementEncryptionSymAlgorithm)
          Defines which symmetric encryption algorithm to use.
 void setSecurementEncryptionUser(String securementEncryptionUser)
          The user's name for encryption.
 void setSecurementMustUnderstand(boolean securementMustUnderstand)
          Enables the mustUnderstand attribute on WS-Security headers on outgoing messages.
 void setSecurementPassword(String securementPassword)
           
 void setSecurementPasswordType(String securementUsernameTokenPasswordType)
          Specific parameter for UsernameToken action to define the encoding of the passowrd.
 void setSecurementSignatureAlgorithm(String securementSignatureAlgorithm)
          Defines which signature algorithm to use.
 void setSecurementSignatureCrypto(Crypto securementSignatureCrypto)
           
 void setSecurementSignatureKeyIdentifier(String securementSignatureKeyIdentifier)
          Defines which key identifier type to use.
 void setSecurementSignatureParts(String securementSignatureParts)
          Property to define which parts of the request shall be signed.
 void setSecurementSignatureUser(String securementSignatureUser)
          The user's name for signature.
 void setSecurementTimeToLive(int securementTimeToLive)
          Sets the time to live on the outgoing message
 void setSecurementUsername(String securementUsername)
          Sets the username for securement username token or/and the alias of the private key for securement signature
 void setSecurementUsernameTokenElements(String securementUsernameTokenElements)
          Sets the additional elements in UsernameTokens.
 void setTimestampPrecisionInMilliseconds(boolean timestampPrecisionInMilliseconds)
          Sets if the generated timestamp header's precision is in milliseconds.
 void setTimestampStrict(boolean timestampStrict)
          Sets whether or not timestamp verification is done with the server-side time to live
 void setTimeToLive(int timeToLive)
          Deprecated. Use setValidationTimeToLive(int) instead.
 void setValidationActions(String actions)
          Sets the validation actions to be executed by the interceptor.
 void setValidationActor(String validationActor)
           
 void setValidationCallbackHandler(CallbackHandler callbackHandler)
          Sets the WSPasswordCallback handler to use when validating messages.
 void setValidationCallbackHandlers(CallbackHandler[] callbackHandler)
          Sets the WSPasswordCallback handlers to use when validating messages.
 void setValidationDecryptionCrypto(Crypto decryptionCrypto)
          Sets the Crypto to use to decrypt incoming messages
 void setValidationSignatureCrypto(Crypto signatureCrypto)
          Sets the Crypto to use to verify the signature of incoming messages
 void setValidationTimeToLive(int validationTimeToLive)
          Sets the server-side time to live
protected  void validateMessage(SoapMessage soapMessage, MessageContext messageContext)
          Abstract template method.
protected  void verifyCertificateTrust(Vector results)
          Verifies the trust of a certificate.
protected  void verifyTimestamp(Vector results)
          Verifies the timestamp.
 
Methods inherited from class org.springframework.ws.soap.security.AbstractWsSecurityInterceptor
handleFault, handleFault, handleFaultException, handleRequest, handleRequest, handleResponse, handleResponse, handleSecurementException, handleValidationException, setExceptionResolver, setSecureRequest, setSecureResponse, setValidateRequest, setValidateResponse, understands
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SECUREMENT_USER_PROPERTY_NAME

public static final String SECUREMENT_USER_PROPERTY_NAME
See Also:
Constant Field Values
Constructor Detail

Wss4jSecurityInterceptor

public Wss4jSecurityInterceptor()
Method Detail

setSecurementActions

public void setSecurementActions(String securementActions)

setSecurementActor

public void setSecurementActor(String securementActor)
The actor name of the wsse:Security header.

If this parameter is omitted, the actor name is not set.

The value of the actor or role has to match the receiver's setting or may contain standard values.


setSecurementCallbackHandler

public void setSecurementCallbackHandler(CallbackHandler securementCallbackHandler)
Sets the WSPasswordCallback handler to use when securing messages.

See Also:
setSecurementCallbackHandlers(CallbackHandler[])

setSecurementCallbackHandlers

public void setSecurementCallbackHandlers(CallbackHandler[] securementCallbackHandler)
Sets the WSPasswordCallback handlers to use when securing messages.

See Also:
setSecurementCallbackHandler(CallbackHandler)

setSecurementEncryptionCrypto

public void setSecurementEncryptionCrypto(Crypto securementEncryptionCrypto)

setSecurementEncryptionEmbeddedKeyName

public void setSecurementEncryptionEmbeddedKeyName(String securementEncryptionEmbeddedKeyName)
Sets the key name that needs to be sent for encryption.


setSecurementEncryptionKeyIdentifier

public void setSecurementEncryptionKeyIdentifier(String securementEncryptionKeyIdentifier)
Defines which key identifier type to use. The WS-Security specifications recommends to use the identifier type IssuerSerial. For possible encryption key identifier types refer to WSHandlerConstants.keyIdentifier. For encryption IssuerSerial, X509KeyIdentifier, DirectReference, Thumbprint, SKIKeyIdentifier, and EmbeddedKeyName are valid only.


setSecurementEncryptionKeyTransportAlgorithm

public void setSecurementEncryptionKeyTransportAlgorithm(String securementEncryptionKeyTransportAlgorithm)
Defines which algorithm to use to encrypt the generated symmetric key. Currently WSS4J supports WSConstants.KEYTRANSPORT_RSA15 and WSConstants.KEYTRANSPORT_RSAOEP.


setSecurementEncryptionParts

public void setSecurementEncryptionParts(String securementEncryptionParts)
Property to define which parts of the request shall be encrypted.

The value of this property is a list of semi-colon separated element names that identify the elements to encrypt. An encryption mode specifier and a namespace identification, each inside a pair of curly brackets, may precede each element name.

The encryption mode specifier is either {Content} or {Element}. Please refer to the W3C XML Encryption specification about the differences between Element and Content encryption. The encryption mode defaults to Content if it is omitted. Example of a list:

 <property name="securementEncryptionParts"
   value="{Content}{http://example.org/paymentv2}CreditCard;
             {Element}{}UserName" />
 
The the first entry of the list identifies the element CreditCard in the namespace http://example.org/paymentv2, and will encrypt its content. Be aware that the element name, the namespace identifier, and the encryption modifier are case sensitive.

The encryption modifier and the namespace identifier can be omitted. In this case the encryption mode defaults to Content and the namespace is set to the SOAP namespace.

An empty encryption mode defaults to Content, an empty namespace identifier defaults to the SOAP namespace. The second line of the example defines Element as encryption mode for an UserName element in the SOAP namespace.

To specify an element without a namespace use the string Null as the namespace name (this is a case sensitive string)

If no list is specified, the handler encrypts the SOAP Body in Content mode by default.


setSecurementEncryptionSymAlgorithm

public void setSecurementEncryptionSymAlgorithm(String securementEncryptionSymAlgorithm)
Defines which symmetric encryption algorithm to use. WSS4J supports the following alorithms: WSConstants.TRIPLE_DES, WSConstants.AES_128, WSConstants.AES_256, and WSConstants.AES_192. Except for AES 192 all of these algorithms are required by the XML Encryption specification.


setSecurementEncryptionUser

public void setSecurementEncryptionUser(String securementEncryptionUser)
The user's name for encryption.

The encryption functions uses the public key of this user's certificate to encrypt the generated symmetric key.

If this parameter is not set, then the encryption function falls back to the WSHandlerConstants.USER parameter to get the certificate.

If only encryption of the SOAP body data is requested, it is recommended to use this parameter to define the username. The application can then use the standard user and password functions (see example at WSHandlerConstants.USER to enable HTTP authentication functions.

Encryption only does not authenticate a user / sender, therefore it does not need a password.

Placing the username of the encryption certificate in the configuration file is not a security risk, because the public key of that certificate is used only.


setSecurementPassword

public void setSecurementPassword(String securementPassword)

setSecurementPasswordType

public void setSecurementPasswordType(String securementUsernameTokenPasswordType)
Specific parameter for UsernameToken action to define the encoding of the passowrd.

The parameter can be set to either WSConstants.PW_DIGEST or to WSConstants.PW_TEXT.

The default setting is PW_DIGEST.


setSecurementSignatureAlgorithm

public void setSecurementSignatureAlgorithm(String securementSignatureAlgorithm)
Defines which signature algorithm to use.

See Also:
WSConstants.RSA, WSConstants.DSA

setSecurementSignatureCrypto

public void setSecurementSignatureCrypto(Crypto securementSignatureCrypto)

setSecurementSignatureKeyIdentifier

public void setSecurementSignatureKeyIdentifier(String securementSignatureKeyIdentifier)
Defines which key identifier type to use. The WS-Security specifications recommends to use the identifier type IssuerSerial. For possible signature key identifier types refer to WSHandlerConstants.keyIdentifier. For signature IssuerSerial and DirectReference are valid only.


setSecurementSignatureParts

public void setSecurementSignatureParts(String securementSignatureParts)
Property to define which parts of the request shall be signed.

Refer to setSecurementEncryptionParts(String) for a detailed description of the format of the value string.

If this property is not specified the handler signs the SOAP Body by default.

The WS Security specifications define several formats to transfer the signature tokens (certificates) or references to these tokens. Thus, the plain element name Token signs the token and takes care of the different formats.

To sign the SOAP body and the signature token the value of this parameter must contain:

 <property name="securementSignatureParts"
   value="{}{http://schemas.xmlsoap.org/soap/envelope/}Body; Token" />
 
To specify an element without a namespace use the string Null as the namespace name (this is a case sensitive string)

If there is no other element in the request with a local name of Body then the SOAP namespace identifier can be empty ({}).


setSecurementSignatureUser

public void setSecurementSignatureUser(String securementSignatureUser)
The user's name for signature.

This name is used as the alias name in the keystore to get user's certificate and private key to perform signing.

If this parameter is not set, then the signature function falls back to the alias specified by setSecurementUsername(String).


setSecurementUsername

public void setSecurementUsername(String securementUsername)
Sets the username for securement username token or/and the alias of the private key for securement signature


setSecurementTimeToLive

public void setSecurementTimeToLive(int securementTimeToLive)
Sets the time to live on the outgoing message


setValidationTimeToLive

public void setValidationTimeToLive(int validationTimeToLive)
Sets the server-side time to live


setTimeToLive

public void setTimeToLive(int timeToLive)
Deprecated. Use setValidationTimeToLive(int) instead.

Sets the server-side time to live


setValidationActions

public void setValidationActions(String actions)
Sets the validation actions to be executed by the interceptor.


setValidationActor

public void setValidationActor(String validationActor)

setValidationCallbackHandler

public void setValidationCallbackHandler(CallbackHandler callbackHandler)
Sets the WSPasswordCallback handler to use when validating messages.

See Also:
setValidationCallbackHandlers(CallbackHandler[])

setValidationCallbackHandlers

public void setValidationCallbackHandlers(CallbackHandler[] callbackHandler)
Sets the WSPasswordCallback handlers to use when validating messages.

See Also:
setValidationCallbackHandler(CallbackHandler)

setValidationDecryptionCrypto

public void setValidationDecryptionCrypto(Crypto decryptionCrypto)
Sets the Crypto to use to decrypt incoming messages


setValidationSignatureCrypto

public void setValidationSignatureCrypto(Crypto signatureCrypto)
Sets the Crypto to use to verify the signature of incoming messages


setEnableSignatureConfirmation

public void setEnableSignatureConfirmation(boolean enableSignatureConfirmation)
Whether to enable signatureConfirmation or not. By default signatureConfirmation is enabled


setTimestampPrecisionInMilliseconds

public void setTimestampPrecisionInMilliseconds(boolean timestampPrecisionInMilliseconds)
Sets if the generated timestamp header's precision is in milliseconds.


setTimestampStrict

public void setTimestampStrict(boolean timestampStrict)
Sets whether or not timestamp verification is done with the server-side time to live


setSecurementMustUnderstand

public void setSecurementMustUnderstand(boolean securementMustUnderstand)
Enables the mustUnderstand attribute on WS-Security headers on outgoing messages. Default is true.


setSecurementUsernameTokenElements

public void setSecurementUsernameTokenElements(String securementUsernameTokenElements)
Sets the additional elements in UsernameTokens.

The value of this parameter is a list of element names that are added to the UsernameToken. The names of the list a separated by spaces.

The list may contain the names Nonce and Created only (case sensitive). Use this option if the password type is passwordText and the handler shall add the Nonce and/or Created elements.


afterPropertiesSet

public void afterPropertiesSet()
                        throws Exception
Specified by:
afterPropertiesSet in interface InitializingBean
Throws:
Exception

secureMessage

protected void secureMessage(SoapMessage soapMessage,
                             MessageContext messageContext)
                      throws WsSecuritySecurementException
Description copied from class: AbstractWsSecurityInterceptor
Abstract template method. Subclasses are required to secure the response contained in the given SoapMessage, and replace the original response with the secured version.

Specified by:
secureMessage in class AbstractWsSecurityInterceptor
Parameters:
soapMessage - the soap message to secure
Throws:
WsSecuritySecurementException - in case of securement errors

validateMessage

protected void validateMessage(SoapMessage soapMessage,
                               MessageContext messageContext)
                        throws WsSecurityValidationException
Description copied from class: AbstractWsSecurityInterceptor
Abstract template method. Subclasses are required to validate the request contained in the given SoapMessage, and replace the original request with the validated version.

Specified by:
validateMessage in class AbstractWsSecurityInterceptor
Parameters:
soapMessage - the soap message to validate
Throws:
WsSecurityValidationException - in case of validation errors

checkResults

protected void checkResults(Vector results,
                            Vector validationActionsVector)
                     throws Wss4jSecurityValidationException
Checks whether the received headers match the configured validation actions. Subclasses could override this method for custom verification behavior.

Parameters:
results - the results of the validation function
validationActionsVector - the decoded validation actions
Throws:
Wss4jSecurityValidationException - if the results are deemed invalid

verifyCertificateTrust

protected void verifyCertificateTrust(Vector results)
                               throws WSSecurityException
Verifies the trust of a certificate.

Throws:
WSSecurityException

verifyTimestamp

protected void verifyTimestamp(Vector results)
                        throws WSSecurityException
Verifies the timestamp.

Throws:
WSSecurityException

cleanUp

protected void cleanUp()
Specified by:
cleanUp in class AbstractWsSecurityInterceptor

Spring Web Services Framework

Copyright © 2005-2010 The Spring Web Services Framework. All Rights Reserved.