Fix Pack 8550

Web Services Security default configuration

A Web Services Security (WS-Security) configuration is complementary to the WS-Security policy at run time. The WS-Security configuration follows the CXF name and value pair style, and preserves the CXF property name. Some of the properties have default values and some do not.

In the server.xml file, the WebSphere® Application Server Liberty profile provides a server-level configuration that is applied to all services. This configuration is known as the default WS-Security configuration.

The server.xml file has two default WS-Security configurations: one for client applications and one for provider applications. No other WS-Security configurations can exist in the server.xml file. If you need a custom WS-Security configuration for your application that deviates from the default, the configuration must be done programmatically.

The following example shows a default client configuration:
<wsSecurityClient id="default"
                  ws-security.username="user2"
                  ws-security.password="security">
  <signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                       org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"
                       org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientCert"
                       org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks"/>
</wsSecurityClient>
The following example shows a default provider configuration:
<wsSecurityProvider id="default"
                    ws-security.username="user2">
  <encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                        org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
                        org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerCert"
                        org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks"/>
</wsSecurityProvider>
The following table shows the default WS-Security user properties in the Liberty profile. These same properties can be found in CXF.
Table 1. Default WS-Security user properties in the Liberty profile and CXF
Liberty profile/CXF property Default value
ws-security.username none
ws-security.password none
ws-security.signature.username none
ws-security.encryption.username none
The following table shows the WS-Security callback handler class and crypto properties in the Liberty profile and the equivalent CXF properties, if different.
Table 2. WS-Security callback handler class and crypto properties in the Liberty profile and the equivalent CXF properties
Liberty profile property CXF property Default value
ws-security.callback-handler   none
<signatureProperties> ws-security.signature.properties none
<encryptionProperties> ws-security.encryption.properties none
In the WebSphere Application Server, the wss4j properties are specified as attributes of the signatureProperties or encryptionProperties elements. The following example shows the wss4j properties:
<signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                     org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"
                     org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientDefault"
                     org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks">
</signatureProperties>
The following table shows the wss4j crypto properties in the Liberty profile. These same properties can be found in CXF.
Table 3. wss4j crypto properties in the Liberty profile and CXF
Liberty profile/CXF property Default value
org.apache.ws.security.crypto.provider

org.apache.ws.security.components.
crypto.Merlin

org.apache.ws.security.crypto.
merlin.keystore.provider

defaults to the installed provider

org.apache.ws.security.crypto.
merlin.cert.provider

defaults to the keystore provider

org.apache.ws.security.crypto.
merlin.x509crl.file

none
The following table shows the wss4j keystore properties in the Liberty profile. These same properties can be found in CXF.
Table 4. wss4j keystore properties in the Liberty profile and CXF
Liberty profile/CXF property Default value

org.apache.ws.security.crypto.
merlin.keystore.file

none

org.apache.ws.security.crypto.
merlin.keystore.password

none

org.apache.ws.security.crypto.
merlin.keystore.type

none

org.apache.ws.security.crypto.
merlin.keystore.alias

none

org.apache.ws.security.crypto.
merlin.keystore.private.password

none
The following table shows the wss4j truststore properties in the Liberty profile. These same properties can be found in CXF.
Table 5. wss4j truststore properties in the Liberty profile and CXF
Liberty profile property Default value

org.apache.ws.security.crypto.
merlin.truststore.file

none

org.apache.ws.security.crypto.
merlin.truststore.password

none

org.apache.ws.security.crypto.
merlin.truststore.type

none
The following table shows the WS-Security miscellaneous properties in the Liberty profile. These same properties can be found in CXF.
Table 6. WS-Security miscellaneous properties in the Liberty profile and CXF
Liberty profile/CXF property Default value
ws-security.enable.nonce.cache true
ws-security.cache.config.file none
The following table shows the properties that are supported only in the Liberty profile.
Table 7. Properties that are supported only in the Liberty profile
Liberty profile property CXF property Default value
callerToken none none

Configuring additional properties

You can set several extra properties to provide additional configuration information to the WS-Security runtime environment. See the following links for detailed information regarding these properties:

Any of the additional properties can be specified in the default WS-Security configuration in the server.xml file.

For example, to specify any additional properties, specify them in either the wsSecurityClient or wsSecurityProvider sections, or both.
<wsSecurityProvider id="default"
  <signatureProperties ... />
  <encryptionProperties ... />
  ws-security.cache.config.file = "${server.config.dir}/resources/ws-security/new_cxf-ehcache.xml"
</wsSecurityProvider>

<wsSecurityClient id="default"
  <signatureProperties ... />
  <encryptionProperties ... />
  ws-security.username-token.always.encrypted="false"
</wsSecurityClient>

Configuring cache

WS-Security provides a default caching implementation for nonce in a UsernameToken, the created Timestamp, and security tokens. The default cache implementation is based on ehCache with the following default settings:
maxEntriesLocalHeap="5000"
timeToIdleSeconds="3600"
timeToLiveSeconds="3600"
overflowToDisk="true"
maxElementsOnDisk="10000000"
diskPersistent="false"
diskExpiryThreadIntervalSeconds="120"
memoryStoreEvictionPolicy="LRU"

To modify the default cache settings, you can provide an ehCache configuration XML file. Use the ws-security.cache.config.file custom property to specify a file name with customized properties to deviate from the default settings. You must put this file somewhere in the server profile. You can find an additional sample cache setting configuration file from http://svn.apache.org/viewvc/cxf/trunk/rt/ws/security/src/main/resources/cxf-ehcache.xml?view=markup.

Configuring a stronger signature algorithm

Because of the weakness of the SHA1 signature algorithm, the US National Institute of Standards and Technology (NIST) recommends that you use stronger signature algorithms.

However, WS-Security policy 1.3 defines HmacSha1 or RsaSha1 (collectively called sha1) as the only signature algorithm. WS-Security in the Liberty profile has a configuration option to use the following stronger signature algorithm:
  • RSA-SHA-256
  • RSA-SHA-384
  • RSA-SHA-512
  • HMAC-SHA-256
  • HMAC-SHA-384
  • HMAC-SHA-512

To configure WS-Security in the Liberty profile to support the stronger signature algorithm, you use the signatureAlgorithm attribute to define the required algorithm within the <signatureProperties> element in the server.xml file. The valid values for the signatureAlgorithm attribute are sha256, sha384, and sha512. For example, if you specify sha512 as the value of the signatureAlgorithm attribute, the signature algorithm that is used in the signature with an asymmetric key is RSA-SHA-512, and the signature algorithm that is used in the signature with a symmetric key is HMAC-SHA-512.

The following example shows a sample client side configuration that requires the sha256 signature algorithm:
<wsSecurityClient id="default"
  ws-security.password="security"
  ws-security.username="user1"
  ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.CommonPasswordCallback"
  ws-security.signature.username="soaprequester">
  <signatureProperties
    signatureAlgorithm="sha256"
    org.apache.ws.security.crypto.merlin.keystore.type="jks"
    org.apache.ws.security.crypto.merlin.keystore.password="client"
    org.apache.ws.security.crypto.merlin.keystore.alias="soaprequester"
    org.apache.ws.security.crypto.merlin.file="${server.config.dir}/dsig-sender.ks" />
</wsSecurityClient>
The following example shows a sample provider side configuration that requires the sha256 signature algorithm:
<wsSecurityProvider id="default"
  ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.CommonPasswordCallback"
  ws-security.signature.username="soapprovider">
  <signatureProperties
    signatureAlgorithm="sha256"
    org.apache.ws.security.crypto.merlin.keystore.type="jks"
    org.apache.ws.security.crypto.merlin.keystore.password="server"
    org.apache.ws.security.crypto.merlin.keystore.alias="soapprovider"
    org.apache.ws.security.crypto.merlin.file="${server.config.dir}/dsig-receiver.ks" /> 
</wsSecurityProvider>

Icon that indicates the type of topic Concept topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-mp&topic=cwlp_wssec_defaultconfig
File name: cwlp_wssec_defaultconfig.html