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

java.lang.Object
  org.springframework.ws.soap.security.AbstractWsSecurityInterceptor
      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 interceptor 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 action	Description
UsernameToken	Validates username token
Timestamp	Validates the timestamp
Encrypt	Decrypts the message
Signature	Validates the signature
NoSecurity	No action performed

Securement actions are:

Securement action	Description
UsernameToken	Adds a username token
UsernameTokenSignature	Adds a username token and a signature username token secret key
Timestamp	Adds a timestamp
Encrypt	Encrypts the response
Signature	Signs the response
NoSecurity	No 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(List<WSSecurityEngineResult> results, List<Integer> validationActions) Checks whether the received headers match the configured validation actions.
protected void	cleanUp()
protected RequestData	initializeRequestData(MessageContext messageContext) Creates and initializes a request data for the given message context.
protected void	secureMessage(SoapMessage soapMessage, MessageContext messageContext) Abstract template method.
void	setBspCompliant(boolean bspCompliant) Set the WS-I Basic Security Profile compliance mode.
void	setEnableRevocation(boolean enableRevocation) Set whether to enable CRL checking or not when verifying trust in a certificate.
void	setEnableSignatureConfirmation(boolean enableSignatureConfirmation) Whether to enable signatureConfirmation or not.
void	setSamlProperties(String location) Sets the location of the SAML properties file.
void	setSecurementActions(String securementActions)
void	setSecurementActor(String securementActor) The actor name of the wsse:Security header.
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	setSecurementSignatureDigestAlgorithm(String digestAlgorithm) Defines which signature digest algorithm to use.
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	setSecurementUseDerivedKey(boolean securementUseDerivedKey) Enables the derivation of keys as per the UsernameTokenProfile 1.1 spec.
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	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
void	setWssConfig(WSSConfig config) Sets the web service specification settings.
protected void	validateMessage(SoapMessage soapMessage, MessageContext messageContext) Abstract template method.
protected void	verifyCertificateTrust(List<WSSecurityEngineResult> results) Verifies the trust of a certificate.
protected void	verifyTimestamp(List<WSSecurityEngineResult> results) Verifies the timestamp.

Methods inherited from class org.springframework.ws.soap.security.AbstractWsSecurityInterceptor

afterCompletion, handleFault, handleFault, handleFaultException, handleRequest, handleRequest, handleResponse, handleResponse, handleSecurementException, handleValidationException, setExceptionResolver, setSecureRequest, setSecureResponse, setSkipValidationIfNoHeaderPresent, 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.

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

setSecurementSignatureDigestAlgorithm

public void setSecurementSignatureDigestAlgorithm(String digestAlgorithm)

Defines which signature digest algorithm to use.

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

setSecurementUseDerivedKey

public void setSecurementUseDerivedKey(boolean securementUseDerivedKey)

Enables the derivation of keys as per the UsernameTokenProfile 1.1 spec. Default is true.

setValidationTimeToLive

public void setValidationTimeToLive(int validationTimeToLive)

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.

setWssConfig

public void setWssConfig(WSSConfig config)

Sets the web service specification settings.

The default settings follow the latest OASIS and changing anything might violate the OASIS specs.

Parameters:

config - web service security configuration or null to use default settings

setEnableRevocation

public void setEnableRevocation(boolean enableRevocation)

Set whether to enable CRL checking or not when verifying trust in a certificate.

setBspCompliant

public void setBspCompliant(boolean bspCompliant)

Set the WS-I Basic Security Profile compliance mode. Default is true.

setSamlProperties

public void setSamlProperties(String location)

Sets the location of the SAML properties file. The file should be available on the classpath.

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

initializeRequestData

protected RequestData initializeRequestData(MessageContext messageContext)

Creates and initializes a request data for the given message context.

Parameters:

messageContext - the message context

Returns:

the request data

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(List<WSSecurityEngineResult> results,
                            List<Integer> validationActions)
                     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

validationActions - the decoded validation actions

Throws:

Wss4jSecurityValidationException - if the results are deemed invalid

verifyCertificateTrust

protected void verifyCertificateTrust(List<WSSecurityEngineResult> results)
                               throws WSSecurityException

Verifies the trust of a certificate.

Throws:

WSSecurityException

verifyTimestamp

protected void verifyTimestamp(List<WSSecurityEngineResult> results)
                        throws WSSecurityException

Verifies the timestamp.

Throws:

WSSecurityException

cleanUp

protected void cleanUp()

Specified by:

cleanUp in class AbstractWsSecurityInterceptor