Apache Rampart - Configuration Guide

Rampart Configurations

RampartConfig element can have any of the following child elements. Schema is available here

ParameterDescriptionExample
userThe user's nameSet username of UsernameToken to be used

<user> bob</user>
userCertAliasThe user's cert aliasSet alias of the key to be used to sign

<userCertAlias> bob</userCertAlias>
encryptionUserThe user's name for encryption. <encryptionUser>alice</encryptionUser>
passwordCallbackClassCallback class used to provide the password required to create the UsernameToken or to sign the message
<passwordCallbackClass>
    org.apache.axis2.security.PWCallback
</passwordCallbackClass>
policyValidatorCbClassCallback class used to provide custom validater
<policyValidatorCbClass>
    org.apache.axis2.security.CustomPolicyValidater
</policyValidatorCbClass>
signatureCryptoproperties to needed perform signature, such as crypto provider, keystore and its password
<signatureCrypto>
	<crypto provider="org.apache.ws.security.components.crypto.Merlin">
		<property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</property>
		<property name="org.apache.ws.security.crypto.merlin.file">client.jks</property>
		<property name="org.apache.ws.security.crypto.merlin.keystore.password">apache</property>
	</crypto>
<signatureCrypto>
encryptionCyptoproperties to needed perform signature, such as crypto provider, keystore and its password
<encryptionCypto>
    ....crypto element ......
</encryptionCypto>
decryptionCryptoproperties to needed perform signature, such as crypto provider, keystore and its password
<decryptionCrypto>
    ....crypto element ......
</decryptionCrypto>
timestampTTLTime to live of TimestampThe default timestamp time to live is 300 seconds
timestampMaxSkewThe maximum tolerence limit for timeskew of the timestampRampart allows timestamps created slightly ahead of the reciever's time.
This parameter allows to specify the tolerence limit
timestampPrecisionInMilliseconds Whether the timestamps precision should be milliseconds When this value is set false, generated timestamps doesn't contain milliseconds
optimizeParts
tokenStoreClass
sslConfigSSL Configuration need for TransportbindingCan specify the properties such as "javax.net.ssl.trustStore" and "javax.net.ssl.trustStorePassword". Please see below for more information.


Crypto Provider

org.apache.ws.security.crypto.provider defines the implementation of the org.apache.ws.security.components.crypto.Crypto interface to provide the crypto information required by WSS4J. The other properties defined are the configuration properties used by the implementation class (org.apache.ws.security.components.crypto.Merlin).

Crypto Caching

Enabling caching of crypto objects will improve the performance of security processing. After enabling crypto caching, the crypto objects will be read from a cache instead of constructing them by reading the keystore files.

To enable caching of Crypto objects, two attributes should be added to the crypto elements of signatureCrypto/encryptionCrypto of RampartConfig.

  1. cryptoKey -

    As the value of this attribute, specify the property of a Crypto implementation which points to the location of the keystore. For example in Merlin, the property "org.apache.ws.security.crypto.merlin.file" is unique and its pointing to the location of the keystore. Absence of this attribute will not enable caching.

  2. cacheRefreshInterval -

    This is the cache refresh interval specified in milliseconds. Any object that resides in the cache longer than this period will be considered as expired. Cache will not be refreshed if this attribute is not present in the configuration. If you do not want to refresh the cache, provide only the "cryptoKey" attribute.

A sample configuration is provided below. It uses the Merlin crypto implementation for signing and encryption. Here, the value of the cryptoKey attribute is eqaul to "org.apache.ws.security.crypto.merlin.file" and the cache refresh interval is 300000 milliseconds.

          <ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy";>
            <ramp:signatureCrypto>
                <ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin" cryptoKey="org.apache.ws.security.crypto.merlin.file" cacheRefreshInterval="300000">
                    <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
                    <ramp:property name="org.apache.ws.security.crypto.merlin.file">service.jks</ramp:property>
                    <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">servicePW</ramp:property>
                </ramp:crypto>
            </ramp:signatureCrypto>
            <ramp:encryptionCypto>
                <ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin" cryptoKey="org.apache.ws.security.crypto.merlin.file" cacheRefreshInterval="300000>
                    <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
                    <ramp:property name="org.apache.ws.security.crypto.merlin.file">service.jks</ramp:property>
                    <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">apache</ramp:property>
                </ramp:crypto>
            </ramp:encryptionCypto>
          </ramp:RampartConfig>
      

Crypto caching is enabled by default when Merlin is used as the crypto provider. So Rampart will cache the crypto objects with an infinite cache refresh interval. This crypto refresh interval can be overridden by setting the cacheRefreshInterval parameter as described above. If it is required to disable crypto caching when Merlin is used, set the 'enableCryptoCaching' parameter value to 'false'. Please refer to the following example.

            <ramp:signatureCrypto>
                <ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin" enableCryptoCaching="false">
                    <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>
                    <ramp:property name="org.apache.ws.security.crypto.merlin.file">service.jks</ramp:property>
                    <ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">servicePW</ramp:property>
                </ramp:crypto>
            </ramp:signatureCrypto>
      


References

1. Apache WSS4J -Home