WS-Security provides means to secure your services above and beyond transport level protocols such as HTTPS. Through a number of standards such as XML-Encryption, and headers defined in the WS-Security standard, it allows you to:

• Pass authentication tokens between services
• Encrypt messages or parts of messages
• Sign messages
• Timestamp messages

Currently, CXF has WS-Security integration which utilizes WSS4J. To use the integration, you'll need to configure these interceptors and add them to your service and/or client.

Overview of encryption and signing

WS-Security makes heavy use of public/private key cryptography. To really understand how to configure WS-Security, it is helpful - if not necessary - to understand how understand these basics. The Wikipedia has an excellent entry on this, but we'll try to summarize the relevant basics here (This content is a modified version of the wikipedia content..

With public key cryptography, a user has a pair of public and private keys. These are generated using a large prime number and a key function.

The keys are related mathematically, but cannot be derived from one another. With these keys we can encrypt messages. For example, if Bob wants to send a message to Alice, he can encrypt a message using her public key. Alice can then decrypt this message using her private key. Only Alice can decrypt this message as she is the only one with the private key.

Messages can also be signed. This allows you to ensure the authenticity of the message. If Alice wants to send a message to Bob, and Bob wants to be sure that it is from Alice, Alice can sign the message using her private key. Bob can then verify that the message is from Alice by using her public key.

Configuring the WSS4J Interceptors

To enable WS-Security within CXF for a server or a client, you'll need to set up the WSS4J interceptors. You can either do this via the API or via Spring XML configuration. This section will provide an overview of how to do this, and the following sections will go into more detail about configuring the interceptors for specific security actions.

Adding the interceptors via the API

On the Server side, you'll want to add the interceptors to your CXF Endpoint. If you're publishing your service using the JAX-WS APIs, you can get your CXF endpoint like this:

EndpointImpl jaxWsEndpoint = (EndpointImpl) Endpoint.publish("http://host/service", myServiceImpl);
Endpoint cxfEndpoint = jaxWsEndpoint.getServer().getEndpoint();

If you've used the (JaxWs)ServerFactoryBean, you can simply access it via the Server object:

ServerFactoryBean factory = ...;
...
Server server = factory.create();
Endpoint cxfEndpoint = server.getEndpoint();

Now you're ready to add the interceptors:

Map<String,Object> inProps= new HashMap<String,Object>();
... // how to configure the properties is outlined below;

WSS4JInInterceptor wssIn = new WSS4JInInterceptor(inProps);
cxfEndpoint.getInInterceptors().add(wssIn);
cxfEndpoint.getInInterceptors().add(new SAAJInInterceptor());

Map<String,Object> outProps = new HashMap<String,Object>();
... // how to configure the properties is outlined below;

WSS4JOutInterceptor wssOut = new WSS4JOutInterceptor(outProps);
cxfEndpoint.getOutInterceptors().add(wssOut);
cxfEndpoint.getOutInterceptors().add(new SAAJOutInterceptor());

It is important to note that

1. You must add the SAAJ*Interceptor if you're using WS-Security. These enabled creation of a DOM for each request/response which is required for WS-Security.
2. You may not need both in and out WS-Security. For instance, if you are just requiring Signature on incoming messages, you'll just need the incoming interceptors.

Configuring WS-Security Actions

Username Token Authentication

Generating keys using keytool

For the Signature and Encryption actions, you'll need to create a public & private key for the entities involved.

For more information, there is an excellent tutorial here.

Signing

Encryption

Timestamp

Importing PFX files

Come soon...