WS-SecureConversation

WS-SecureConversation support in CXF builds upon the WS-SecurityPolicy implementation to handle the SecureConversationToken policy assertions that could be found in the WS-SecurityPolicy fragment.

Note: Because the WS-SecureConversation support builds on the WS-SecurityPolicy support, this is currently only available to "wsdl first" projects.

One of the "problems" of WS-Security is that the use of strong encryption keys for all communication extracts a hefty performance penalty on the communication. WS-SecureConversation helps to alleviate that somewhat by allowing the client and service to use the strong encryption at the start to negotiatate a set of new security keys that will be used for furthur communication. This can be a huge benefit if the client needs to send many requests to the service. However, if the client only needs to send a single request and then is discarded, WS-SecureConversation is actually slower as the key negotiation requires an extra request/response to the server.

With WS-SecureConversation, there are two Security policies that come into effect:

1. The "outer" policy that describes the security requirements for interacting with the actual endpoint. This will contain a SecureConversationToken in it someplace.
2. The "bootstrap" policy that is contained in the SecureConversationToken. This policy is the policy in affect when the client is negotiating the SecureConversation keys.

Configuring the WS-SecurityPolicy properties for WS-SecureConversation works exactly like the configuration for straight WS-SecurityPolicy. The only difference is that there needs to be a way to specify which properties are intended for the bootstrap policy in the SecureConversationToken and which are intended for the actual service policy. To accomplish this, properties intended for the SecureConversationToken bootstrap policy are appended with ".sct". For example:

<jaxws:client name="{http://InteropBaseAddress/interop}XDC-SEES_IPingService" 
    createdFromAPI="true">
    <jaxws:properties>
        <!-- properties for the external policy -->
        <entry key="ws-security.username" value="abcd"/>

        <!-- properties for the SecureConversationToken bootstrap policy -->
        <entry key="ws-security.username.sct" value="efgh"/>
        <entry key="ws-security.callback-handler.sct" 
               value="interop.client.KeystorePasswordCallback"/>
        <entry key="ws-security.encryption.properties.sct" 
               value="etc/bob.properties"/> 
    </jaxws:properties>
</jaxws:client>   

Via the Java API, use code similar to the following:

org.apache.cxf.endpoint.Client client;
client.getRequestContext().put("ws-security.username.sct", username);
client.getRequestContext().put("ws-security.password.sct", password);

Via the Java API, use code similar to the following:

org.apache.cxf.endpoint.Client client;
client.getRequestContext().put("ws-security.username.sct", username);
client.getRequestContext().put("ws-security.password.sct", password);

Note: In most common cases of WS-SecureConversation, you won't need any configuration for the service policy. All of the "hard" stuff is used for the bootstrap policy and the service provides new keys for use by the service policy. This keeps the communication with the service itself as simple and efficient as possible.