Skip to main content Skip to complementary content

WS-SecureConversation

About this task

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 carries a hefty performance penalty on communication. WS-SecureConversation helps to alleviate that somewhat by allowing the client and service to use strong encryption at the start to negotiate 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 is then discarded, WS-SecureConversation is actually slower because the key negotiation requires an extra request/response to the server.

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

Procedure

  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 SecureConverstationToken. This policy is the policy in affect when the client is negotiating the SecureConversation keys.

Results

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 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.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – let us know how we can improve!

Leave your feedback here