Colm O hEigeartaigh: UsernameToken Derived Key support in Apache CXF

Support for UsernameToken derived keys has been added to Apache CXF and will be available in the forthcoming 2.4.7 and 2.5.3 releases. UsernameTokens are usually used for authentication, where an initiator places a username and password (plaintext or digested) in the security header of a Soap request. However, it is also possible to exploit the fact that the initiator and recipient share a common secret (the password), by deriving a key from the UsernameToken to perform message level encryption or signature. This functionality provides an alternative to the usual certificate-based approach involved in message level security.

The WS-Security UsernameToken 1.1 profile describes how to derive keys from a UsernameToken. The UsernameToken does not include a password in this case, but includes Username, Salt and (an optional) Iteration elements. The Salt is a 128 bit value, where the high-order 8 bits have the value 01 when it is used for signature, and 02 when used for encryption. This implies that a key derived from a UsernameToken can be used for either signature or encryption, but not both. 

1) Running the UsernameToken derived key system tests in Apache CXF 

The best way to understand how to use this functionality is to take a look at the system tests. To run the UsernameToken derived key system tests in CXF, make sure that the JDK has unlimited security policies installed, and then checkout the CXF trunk via:

svn co https://svn.apache.org/repos/asf/cxf/trunk/

Go into the "trunk" directory, and compile and install CXF via "mvn -Pfastinstall" (this will avoid running tests). Finally go into the WS-Security system tests in "systests/ws-security". The UsernameTokenDerivedTest contains a number of tests that show how to use keys derived from Username Tokens to secure a message exchange. The service and client endpoints are spring-loaded. If you want to see the message exchanges, open src/test/resources/logging.properties, and change the level from WARNING to INFO, and the ConsoleHandler level from SEVERE to INFO. Finally, run the tests via:

        mvn test -Dtest=UsernameTokenDerivedTest

2) WS-SecurityPolicy configuration

The wsdl that defines the service endpoints contains WS-SecurityPolicy expressions that define the security requirements of the endpoints. The following security policies are used for the tests:

• DoubleItSymmetricProtectionPolicy: This uses a Symmetric binding, where the protection token is a UsernameToken. In other words, a key is derived from the UsernameToken according to the spec, and is used to encrypt or sign the message request.
• DoubleItSymmetricProtectionDKPolicy: This is the same as above, except that instead of using the UsernameToken derived key directly, another derived key is used instead.
• DoubleItSymmetricProtectionEncPolicy: This is the same policy as above, except that it is used for encryption and not signature. It does not include a Timestamp requirement, as this would require that the Timestamp be signed.
• DoubleItTransportEndorsingPolicy: This uses a Transport binding, where a UsernameToken is included as an EndorsingSupportingToken. In other words, the key derived from the UsernameToken is used to sign the Timestamp.
• DoubleItSymmetricSignedEndorsingPolicy: This uses a Symmetric binding, where a UsernameToken is included as a SignedEndorsingSupportingToken. 
• DoubleItSymmetricEndorsingEncryptedPolicy: This uses a Symmetric binding, where a UsernameToken is included as a EndorsingEncryptedSupportingToken.
• DoubleItSymmetricSignedEndorsingEncryptedPolicy: This uses a Symmetric binding, where a UsernameToken is included as a SignedEndorsingEncryptedSupportingToken. 

UsernameToken derived keys are not currently supported with the Asymmetric binding.