JDK Repair

The upgrade process kindly removed all of my previously installed JDKs under /Library/Java/JavaVirtualMachines.  This deletion had the added benefit of messing up my installed JVMs in Eclipse.  Since the built-in JVM does not contain source code, I had to reinstall the developer package for the JDK.   After a little venting about the intelligence of the engineer who made that decision, I was off to connect.apple.com to look for the OS X 10.7 JDK installer.  Luckily the fix is the same as the process I described in the Installing the JDK and the Looking at the JDK files sections my earlier post, and I was up and running without too much additional frustration.

One thing of note is that the JDK installers did not appear in the download list when I first logged in, even after using the site’s search feature.  If you find yourself in a similar position, the direct download link for the “Java for Mac OS X 10.7 Developer Package” installer as of the publishing of this post is https://developer.apple.com/downloads/download.action?path=Java/java_for_mac_os_x_10.7_developer_package/javadeveloper_for_mac_os_x_10.7__11a511.dmg

Insomia X

The upgrade breaks InsomniaX.  For me it would still start, but it would not prevent the laptop from going to sleep.  InsomniaX 2.0 adds Lion support.

Git

It looks like the upgrade may have also removed a symbolic link to my Git installation.  The installation was not removed, but I had to create or recreate a link in /usr/local/bin.

The Project and Build Structure

One of the easiest ways to assemble an OSGi ready WAR is to use Maven in conjunction with the WAR and Felix Bundle Plug-ins. The WAR Plug-in allows the build to produce a WAR artifact while the Bundle Plug-in simplifies the creation of the OSGi manifest. The following Maven POM snippet illustrates the key points of the Maven build. The complete POM can be found in the source code repository.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
  ...
  <packaging>war</packaging>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- Make a skinny WAR -->
          <packagingExcludes>WEB-INF/lib/*.jar</packagingExcludes>
          <archive>
            <manifestFile>${basedir}/target/bnd/MANIFEST.MF</manifestFile>
          </archive>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>2.3.5</version>
        <executions>
          <execution>
            <id>bundle-manifest</id>
            <phase>process-classes</phase>
            <goals>
              <goal>manifest</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <supportedProjectTypes>
            <supportedProjectType>war</supportedProjectType>
          </supportedProjectTypes>
          <manifestLocation>target/bnd</manifestLocation>
          <instructions>
            <Webapp-Context>spring-mvc-smx</Webapp-Context>
            <Web-ContextPath>spring-mvc-smx</Web-ContextPath>
            <Export-Package>!*</Export-Package>
            <Import-Package>
              javax.servlet; version="[2.4.0, 4.0.0)",
              javax.servlet.http; version="[2.4.0, 4.0.0)",
              javax.servlet.jsp.jstl.core; version="[1.2,2.0)",
              javax.servlet.resources; version="[2.4.0, 4.0.0)",
              <!-- Just import EVERYTHING from Apache standard JSTL impl. -->
              org.apache.taglibs.standard; version="[1.2.0,2)",
              org.apache.taglibs.standard.extra.spath; version="[1.2.0,2)",
              org.apache.taglibs.standard.functions; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl.parser; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl.test; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.jstl.test.beans; version="[1.2.0,2)",
              org.apache.taglibs.standard.lang.support; version="[1.2.0,2)",
              org.apache.taglibs.standard.resources; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.core; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.fmt; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.sql; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.common.xml; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.core; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.fmt; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.sql; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.el.xml; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.core; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.fmt; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.sql; version="[1.2.0,2)",
              org.apache.taglibs.standard.tag.rt.xml; version="[1.2.0,2)",
              org.apache.taglibs.standard.tei; version="[1.2.0,2)",
              org.apache.taglibs.standard.tlv; version="[1.2.0,2)",
              org.springframework.beans.factory.config,
              org.springframework.osgi.web.context.support; version="[1.2,2.0)",
              org.springframework.stereotype,
              org.springframework.web.bind.annotation,
              org.springframework.web.servlet,
              org.springframework.web.servlet.view,
              *
            </Import-Package>
            <Bundle-ClassPath>
              WEB-INF/classes,
              <!-- Have to use this for PAX Web 0.7.4 to find JSPs since it uses classpath. -->
              .
            </Bundle-ClassPath>
          </instructions>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
</project>

• Line 4 – This line is the standard way in which you instruct Maven to construct a WAR artifact instead of the default JAR packaging.
• Line 13 – This line instructs the WAR Plug-in to exclude all dependencies from the WAR. The resulting WAR imports all of its dependencies from the OSGi class loader and is therefore significantly smaller than a traditional WAR.
• Line 15 – This line instructs the WAR Plug-in to use an externally generated manifest file instead of the one that is automatically generated by default.
• Line 28 – This line instructs the Felix Bundle Plug-in to generate a manifest file on the file system when the plug-in is executed. Normally, the plug-in injects the manifest directly into the artifact; however, this behavior conflicts with that of the WAR plug-in so we configure this plug-in to write the file to disk and we configure the WAR Plug-in to use the manifest file from the file system.
• Line 34 – This line instructs the Felix Bundle Plug-in to execute for projects with the WAR packaging type. The plug-in will not execute for this type of packaging by default.
• Line 36 – This line indicates where the Felix Bundle Plug-in should write the manifest file. Note that this location aligns with the location that the WAR Plug-in reads the manifest file from.
• Lines 38-39 – These lines provide the context path for the Web application when it is deployed. The context path is the portion of the path preceding the application specific path. In this case, all application URLs will start with http://HOST:PORT/spring-mvc-smx. This property is specified twice in order to support a wider range of PAX Web Extender versions. Web-ContextPath is the official OSGi header while Webapp-Context is the PAX Web Extender specific header supported in earlier versions of PAX Web. PAX Web is the implementation of the WAR related OSGi capabilities that is used in ServiceMix. This library is responsible or connecting the WAR to the underlying OSGi framework as well as publishing the WAR to the OSGi HTTP Service.
• Lines 42-45 – These lines indicate that the OSGi container, through its class loading mechanism, should provide the standard Servlet API classes. Much like standard WAR deployments, the container frequently provides these API classes to the class path.
• Lines 46-69 – These lines indicate that the OSGi container should provide the Apache implementation of the JSTL to the WAR. In this case, we simply import all of the packages that the Apache “standard” JSTL implementation library exports. These package imports are required if your application includes JSPs that leverage the JSTL tags, but may vary if you choose to use a different implementation. Providing these packages from the container instead of WEB-INF/lib means that your WAR size can be reduced and the implementation library can be shared across multiple WARs. As these packages are not directly referenced from compiled code, they are not automatically detected by the plug-in and therefore must be manually specified.
• Line 70-75 – These lines indicate that the OSGi container should provide the necessary Spring MVC classes from the OSGi class loader and not from WEB-INF/lib. As with the Apache JSTL implementation, these packages are not directly referenced from compiled code and are therefore not detected by the Felix Bundle Plug-in. These packages must be imported from the OSGi container to ensure a consistent class space with the Spring DM OsgiBundleXmlWebApplicationContext class.
• Lines 79-81 – These lines indicate that the bundle/WAR class path should also include the contents of specific locations within the WAR. The WEB-INF/classes folder provides the implementation classes for the WAR while the “.” entry is required to enable the PAX Web Extender to locate JSPs within the WAR. Some versions of the PAX Web Extender search for the JSP path using the WAR/bundle class path in lieu of searching the actual bundle/WAR contents. As such, including the root folder of the bundle/WAR on the class path ensures that JSPs can be resolved over a broader range of PAX Web versions.

The project folder structure is as follows:

• /src/main/java – This folder contains the source code for the WAR.
• /src/main/features – This folder contains the source file for the project Karaf Feature Descriptor.
• /src/main/webapp – This folder contains the contents that are copied into the root of the WAR. This folder contains JSPs, web.xml, and the Spring MVC application context file.

Spring MVC In an OSGi World

Spring MVC typically uses an XmlWebApplicationContext instance with the DispatcherServlet. Together, these two classes provide a means to bootstrap a Servlet container aware application context and to wire the Servlet container to the Spring MVC controllers. XmlWebApplicationContext is however, unaware of the OSGi container. For this reason, Spring DM provides an OsgiBundleXmlWebApplicationContext that can be substituted for XmlWebApplicationContext when deploying the WAR in an OSGi container. OsgiBundleXmlWebApplicationContext makes the application context in the WAR aware of the OSGi container and provides access to the capabilities provided by the container as well as the BundleContext of the deployed bundle/WAR. One specifies that the DispatcherServlet should use the OSGi aware version of the application context in the web.xml file of the bundle/WAR. The following web.xml snippet illustrates the relevant configuration. After this small change, the standard features of Spring and Spring MVC, including annotation based controllers and component scanning, are available within the OSGi deployed WAR. The complete web.xml can be found in the source code repository.

…
  <servlet>
    <servlet-name>spring-mvc-smx</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextClass</param-name>
      <param-value>org.springframework.osgi.web.context.support.OsgiBundleXmlWebApplicationContext</param-value>
    </init-param>
  </servlet>
…

• Lines 5-8 – Illustrate using an init-param for the DispatcherServlet to override the implementation class for the application context used by the servlet.

Tag Libraries in an OSGi World

Normally, tag libraries can be auto-detected from the WEB-INF/lib folder or specified in the web.xml file. As this example does not specify any JAR files from WEB-INF/lib in the Bundle-Classpath manifest header, the tag library implementation must be provided by the OSGi container class loader through a package import. While this approach does not require the tag library implementation to be included in the WAR itself, it does create a small issue with auto-discovery of the .tld files for the tag library. Tag library descriptor files reside in the META-INF folder of the JAR. When this JAR is not in the WEB-INF/lib folder and its packages are instead supplied by OSGi package imports, these files are not detected. The workaround for this limitation is to include the tag library descriptor files directly in the WAR and to reference them from web.xml. The following web.xml snippet illustrates the relevant configuration settings for including the JSTL .tld files from withing the WAR itself. The complete web.xml can be found in the source code repository.

…
  <jsp-config>
    <taglib>
      <taglib-uri>http://java.sun.com/jstl/core</taglib-uri>
      <taglib-location>/WEB-INF/tld/c.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/fmt</taglib-uri>
      <taglib-location>/WEB-INF/tld/fmt.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/fmt</taglib-uri>
      <taglib-location>/WEB-INF/tld/fmt.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/functions</taglib-uri>
      <taglib-location>/WEB-INF/tld/fn.tld</taglib-location>
    </taglib>
    <taglib>
      <taglib-uri>http://java.sun.com/jsp/jstl/xml</taglib-uri>
      <taglib-location>/WEB-INF/tld/x.tld</taglib-location>
    </taglib>
  </jsp-config>
…

• Lines 2-23 – These lines provide the location for the TLD files of the JSTL. The files were copied from the implementation JAR that the bundle/WAR imports the JSTL implementation packages from. Alternatively, the JSTL implementation JAR can be included in the WAR and added to the Bundle-Classpath manifest header; however, the bundle/WAR will then need to import the package dependencies from the implementation JAR or also add those dependencies to the Bundle-Classpath manifest header.

Bridging the OSGi WAR Gap

So far this article has discussed how to get Spring MVC to act like Spring MVC in an OSGi deployed WAR. If there were nothing more, the keener reader’s out there would be asking, “why would I go through all this trouble when Servlet container XXX will do just fine?” Don’t worry if you didn’t ask this question, you are already researching this topic and reading a blog. That makes you more keen than not. Because the WAR is using OsgiBundleXmlWebApplicationContext from Spring DM, all of the OSGi goodness that Spring DM brings to Spring is also available to the Spring MVC based applications. Service implementations for Spring MVC controllers can be looked up in the OSGi service registry, configuration options can be managed and updated through the OSGi Configuration Admin service, and previously insurmountable class space collisions can be overcome. The following Spring application context snippet illustrates one of the many convenient integration points that Spring DM can provide to the Web application. More examples of the Spring DM capabilities are available in the Spring DM documentation. The complete context file can be found in the source code repository.

...
<osgi:reference id="configurationAdmin"
                  interface="org.osgi.service.cm.ConfigurationAdmin"/>
...

• Lines 2-3 – This line illustrates how to retrieve a service from the OSGi registry. In this case, the service is the Configuration Admin service. The controller in the example application uses this service to list all of the configurations available in the OSGi container.

Once available in the application context, the bean can be used just as any other locally defined bean. The following Java snippet illustrates how the bean is injected into a controller and used to render the view.  The complete controller source is available in the source repository.

...

@Controller
@RequestMapping(value = "/")
public class HomeController {

    @Autowired
    BundleContext bundleContext;

    @Autowired
    ConfigurationAdmin configurationAdmin;

    RequestMapping(method = {RequestMethod.GET})
    public ModelAndView home() throws Exception {

        ModelAndView mav = new ModelAndView("home");

        Bundle[] bundles = bundleContext.getBundles();
        mav.addObject("bundles", bundles);

        Configuration[] configurations = configurationAdmin.listConfigurations(null);
        mav.addObject("configurations", configurations);
        return mav;
    }

    public BundleContext getBundleContext() {
        return bundleContext;
    }

    public void setBundleContext(BundleContext bundleContext) {
        this.bundleContext = bundleContext;
    }

    public ConfigurationAdmin getConfigurationAdmin() {
        return configurationAdmin;
    }

    public void setConfigurationAdmin(ConfigurationAdmin configurationAdmin) {
        this.configurationAdmin = configurationAdmin;
    }
}

• Line 11 – This line declares an instance of the Configuration Admin interface as an instance variable that is set using Spring’s auto-wiring.
• Lines 14-23 – These lines query the Configuration Admin service and add the results to the model for rendering.

Deploying in Apache ServiceMix

In order to deploy a WAR using Spring MVC and the Apache JSTL implementation, several additional OSGi bundles must be provisioned in an out-of-the-box ServiceMix instance. The easiest and most repeatable way to provision these bundles is to use a Karaf feature descriptor to describe the bundles to be provisioned. The following feature descriptor snippet illustrates the additional provisioning activities that are needed. The complete feature descriptor can be found in the source code repository.

<?xml version="1.0" encoding="UTF-8"?>
<features name="spring-mvc-smx-${project.version}">
  <feature name="spring-mvc-smx" version="${project.version}">
    <feature>spring</feature>
    <feature>spring-dm</feature>
    <feature>war</feature>

    <bundle>mvn:${project.groupId}/spring-mvc-smx/${project.version}/war</bundle>

    <bundle>mvn:org.springframework.osgi/spring-osgi-web/1.2.0</bundle>
    <bundle>mvn:org.springframework/spring-web/3.0.5.RELEASE</bundle>
    <bundle>mvn:org.springframework/spring-webmvc/3.0.5.RELEASE</bundle>

    <bundle>mvn:javax.servlet/com.springsource.javax.servlet.jsp.jstl/1.2.0.v20110728</bundle>
  </feature>
</features>

• Lines 4-6 – These lines ensure that the core Spring bundles, the core Spring DM bundles, and the PAX Web bundles are provisioned in the container.
• Lines 10-12 – These lines provision the additional Spring DM and Spring MVC bundles required to deploy a WAR using Spring MVC.
• Line 14 – These lines provision the bundle related to the Apache implementation of the JSTL.

Building and Deploying the Example Code

Build Pre-requisites

• Java 1.5+
• Maven 3.0+
• Subversion

Deploy Pre-requisites

• Apache ServiceMix 4.3.0

Building

1. Checkout the source code from https://davidvaleri.googlecode.com/svn/projects/examples/spring-mvc-smx/tags/spring-mvc-smx-1.0 using your Subversion client.
2. Build the source code by executing the following command from the checkout folder:

   mvn clean install

Deploying

1. Start Apache ServiceMix 4.3.0
2. In the ServiceMix shell, add the feature descriptor for the example application by executing the following command:

   features:addurl mvn:valeri.blog.examples/spring-mvc-smx/1.0/xml/features

   NOTE: If you did not build the example locally, you will need to add the Maven repository for this blog to the ServiceMix configuration. Edit SERVICEMIX_HOME/etc/org.ops4j.pax.url.mvn.cfg and add http://davidvaleri.googlecode.com/svn/repo/ to the org.ops4j.pax.url.mvn.repositories property.

3. Provision the example WAR by executing the following command in the ServiceMix shell:
   features:install spring-mvc-smx
4. Confirm the installation by executing the following command in the ServiceMix shell:
   osgi:list
5. The output should resemble the following:

   [ 202] [Active ] [ ] [ ] [ 60] David Valeri's Blog :: Examples :: Spring MVC In ServiceMix (1.0.0)
   [ 203] [Active ] [ ] [ ] [ 60] spring-osgi-web (1.2.0)
   [ 204] [Active ] [ ] [ ] [ 60] Spring Web (3.0.5.RELEASE)
   [ 205] [Active ] [ ] [ ] [ 60] Spring Web Servlet (3.0.5.RELEASE)
   [ 206] [Active ] [ ] [ ] [ 60] JavaServer Pages (TM) TagLib API and Implementation (1.2.0.v20110728)

6. Navigate to http://localhost:8181/spring-mvc-smx/ using the browser of your choice.
7. The displayed page contains information retrieved from the OSGi bundle context as well as from an OSGi service retrieved from the OSGi service registry. If you receive an error message or no page is displayed, try refreshing the WAR bundle as it may have loaded before the other newly provisioned bundles. Execute the refresh in the ServiceMix shell using the ID of the bundle with the name “David Valeri’s Blog :: Examples :: Spring MVC In ServiceMix (1.0.0)”. If you still receive an error message, refer to the ServiceMix log files and feel free to post a comment below.

One of Camel’s greatest strengths is to abstract the complexity of framework boilerplate code away from one’s application.  Unfortunately, when it comes to TLS configuration, Camel just wasn’t doing enough to prevent developers needing to configure TLS for a component from having to implement framework specific interfaces, learn framework specific configuration options, and generally curse TLS and JSSE.  This observation coupled with a healthy does of frustration served as the impetuous for creating the JSSE Configuration Utility in Apache Camel.

The key goals of the configuration utility are:

1. Provide a uniform framework for complete customization of JSSE/TLS configuration options from key stores, to algorithms, to protocols, to sockets.
2. Provide an easy way to configure these options through code, Spring, and Blueprint.
3. Provide extensibility to allow for the addition of future configuration options.
4. Provide support for the configuration utility across a number of key networking related Camel components.

The JSSE Configuration Utility is available in Camel 2.8 and above.  You can read about the capabilities of the JSSE Configuration Utility and see a list of components with support for the utility on the Apache Camel Wiki.  Support for the new Camel Asynchronous HTTP Client component is planed for Camel 2.9.  If you are looking for an enterprise-ready, validated, and supported distribution of Apache Camel, try Fuse Mediation Router which is based on Apache Camel.

Before we begin, this article assumes that you have a working knowledge of OSGi bundles and a basic understanding of how to use the Felix Bundle Plug-in with a Maven build.  For more information on OSGi and the Felix Bundle Plug-in, refer to the links below.

• http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html
• http://www.aqute.biz/Bnd/Bnd
• http://www.google.com/search?q=osgi+tutorial

The Default Plug-in Behavior

The simplest strategy that comes to mind is to just let the bundle plug-in loose on your build and let it choose the version range on each package import. The bundle plug-in’s default behavior is to create a range from a dependency’s current version, truncated to only the major and minor version, up to but not including the next major version number. For example, if your project depends on package x.y.z from another OSGi bundle with the package export version 1.2.3.4, the resulting import will use the version range from 1.2 up to, but not including, 2. The import will look like this:

x.y.z; version="[1.2,2)"

Manually Specifying Versions

The next level of control over the package imports in your bundle is to use Maven properties in your POM to define version numbers and to use token replacement in the configuration of the Felix Bundle Plug-in.  You can also just hard-code the literals in the bundle plug-in, but this requires a little more attention to detail when performing POM maintenance. This approach allows you to manually set a variable representing the version of a given library and to reuse it a number of times across multiple configurations of the Felix Bundle Plug-in. This approach looks something like the following POM snippet.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  …
  <properties>
    <camel.version>2.6.0-fuse-01-09</camel.version>
  </properties>
  …
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>2.3.4</version>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Import-Package>
              org.apache.camel*; version="${camel.version}",
              *
            </Import-Package>
          </instructions>
        </configuration>
      </plugin>
    </plugins>
  </build>
  …
</project>

This POM snippet instructs the Felix Bundle Plug-in to import all Camel related packages with a strict version requirement on the version represented by the value of the camel.version property in the POM, 2.6.0-fuse-01-09 in this example. All other packages will be imported using the default range chosen by the Felix Bundle Plug-in.

This approach quickly becomes tedious to maintain if you want to retain ranges on your package imports as you would need to define properties for both the upper and lower bounds of every import as well as keep all those properties properly sorted in your POM.

Using the BND Macros

The BND tool, the underlying utility that the Felix Bundle Plug-in is built on, provides a number of predefined macros for working with version numbers on package imports. The most common macros, are @, version, and range. These macros represent the version of the package as supplied by your maven resolved dependencies, a configurable mask applied to a version number, and a range built using a mask applied to a version number, respectively. While these macro capabilities sound great, the BND tool documentation isn’t always up to date nor does the Felix Bundle Plug-in describe the use of these macros in much detail. The following examples should help to clarify the behavior of the Felix Bundle Plug-in (version 2.3.4) and the use these macros in the context of the plug-in as it isn’t always obvious and there are a couple gotchas. Before I continue, I’d like to thank Fintan Bolton, tech writer extraordinaire from FuseSource. Fintan helped to put some of the pieces in place and I am happy to say that the following information already appears in, or will appear shortly, in the FuseSource documentation on Apache ServiceMix and OSGi.

Caveat Emptor

The First Gotcha

Maven uses the ${} pattern for its own token replacement mechanism. While the BND tool also allows the ${} pattern to be used for its macros, keep in mind that Maven will process the plug-in configuration first and happily replace your ${@} macro usage with its own value for the @ property.
So this in your POM:

org.slf4j;version="${@}

Results in this in your bundle manifest:

org.slf4j;version=null

Suitable substitutes for ${} in the Felix Bundle Plug-in are: $() and $<>. Note that when using <> as your macro delimiters, you either need to escape < with &lt; or wrap the contents of the element with CDATA as shown below.  The CDATA approach is far more manageable over the long term as it is much easier to read and maintain.

<Import-Package><![CDATA[
  *;version="$<@>"]]>
</Import-Package>

The Second Gotcha

The plug-in and BND are not looking out for dependencies that are a plain JAR. For example, the JSR 303 API JAR in the Maven repo is not an OSGi bundle. If you attempt to use one of the macros on any package from this JAR, you will get the literal text of the macro instead of a version number in your bundle manifest.
This in your POM:

javax.validation;version="$(@)"

Results in this in your bundle manifest:

javax.validation;version="${@}"

The Third Gotcha

The plug-in and BND are not looking out for dependencies that that do not define a version on their exported packages. For example, WSS4J 1.5.8 is packaged as an OSGi bundle, but its package exports do not define a version number in the bundle manifest. A reference to a package from WSS4J using one of the three macros discussed in this article will also result in the literal text of the macro instead of a version number in your bundle manifest.
This in your POM:

org.apache.ws.security;version="$(@)"

Results in this in your bundle manifest:

org.apache.ws.security;version="${@}"

The @ Macro

This macro will inject the version of a package as it is provided in a Maven defined dependency in the build classpath. In the following POM, the source code leverages packages from SLF4J.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  …
  <dependencies>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
      <version>1.5.8</version>
    </dependency>
  </dependencies>
  …
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>2.3.4</version>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Import-Package>
              *;version="$(@)"
            </Import-Package>
          </instructions>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

The resulting bundle manifest will contain the following:

Import-Package: org.slf4j;version="1.5.8"

The Version Macro

This macro will inject the version of a package, either defined by the version as it is provided in a Maven defined dependency or as supplied as a literal, after it has had a mask applied to it. The mask allows you to easily alter a package version declaratively during the build process. The “=” mask indicates to leave that portion of the version alone, the “+” mask indicates to increment that portion of the version, and the “-“ filter indicates to decrement that portion of the version.

For example if package x.y.z has the version 1.2.3.4, the mask ==== would result in the version 1.2.3.4, the mask =+ would result in the version 1.3, and the mask =- would result in the version 1.1.

The syntax for this macro in version 2.3.4 of the Felix Bundle Plug-in is a little different than described in the BND documentation. The syntax is version;MASK[;LITERAL]. Where MASK is a combination of mask characters and ;LITERAL represents an optional literal version number string. If the literal version number string is omitted, an implicit @ macro is used. The following package import is a valid example of the version macro in 2.3.4.

org.slf4j*;version="[$(version;==),$(version;+;1.5.8))"

This configuration indicates to construct a version range with the lower bound containing only the major and minor version number of the version defined in the SL4J dependency resolved by Maven and the upper bound containing only the major version number, incremented by one, of the literal version string 1.5.8. The literal value can also be supplied by Maven token replacement. So the line from the above example becomes:

org.slf4j*;version="[$(version;==),$(version;+;${slf4j.version}))"

While one can use the version macro to define a version rage for package imports, the range macro makes this task even simpler in many cases.

The Range Macro

The range macro works much like the version macro by applying a mask to a version number; however, this macro also allows you to inject the inclusive/exclusive wrapper characters of the OSGi version range syntax. The following POM snippet illustrates how to create a version range for the SLF4J packages used throughout this article. The module source code contains imports for packages supplied by SLF4J.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  …
  <dependencies>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
      <version>1.5.8</version>
    </dependency>
  </dependencies>
  …
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>2.3.4</version>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Import-Package><![CDATA[
              org.slf4j*;version="$<range;[==,=+)>"
              ]]>
            </Import-Package>
          </instructions>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

The resulting bundle manifest will contain the following:

Import-Package: org.slf4j;version="[1.5,1.6)"

In this case, the implicit @ macro was used to determine the version number to apply the masks to. Just like the version macro, you can also specify a version number as a string literal or using a Maven property and token replacement.

Note also that the < and > characters were chosen as the separators in this case. This is because the ) character used to close the version range will confuse the parser if the ( and ) characters are used to demarcate the range macro.

This configuration using the ( and ) characters to demarcate the range:

org.slf4j*;version="$(range;[==,=+))"

Results in the following error message during the build:

[INFO] [bundle:bundle {execution: default-bundle}]
[WARNING] Warning building bundle example:bundle-plugin-macros:bundle:1.0 : No translation found for macro: range;[==,=+
[ERROR] Error building bundle example:bundle-plugin-macros:bundle:1.0 : null, for cmd: range, arguments; [range, [==,=+]
[ERROR] Error(s) found in bundle configuration
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Error(s) found in bundle configuration

Conclusion

While the documentation on these macros and the Felix Bundle Plug-in may not provide a massive amount of detail, once you understand the syntax and pitfalls of the macros, they can be combined in a number of ways to provide rich control over package imports in your bundles.

Having spent so much time in Windows, I was somewhat nervous about how I would adapt to the Mac way of doing things.  I am certainly not what you would call a Steve Jobs fan-boy and I was ready to slap Linux/Windows on the thing after a couple weeks if it wasn’t working out.  Overall, the migration has been relatively painless and there are only a few nagging things I feel like I need to resolve.  I don’t hate Windows, but the amount of superfluous corporate bloat on the Windows machine made the simple act of rebooting into a 5 minute ordeal, not to mention the mess that 20 Subversion based source code checkouts caused when compounded with the virus scanner and the backup software.

Being an open source developer and loving anything free, as in beer and speech, this article will focus on free applications even if there is a more capable commercial solution available.  I hope this article saves you some time on your journey from Windows to OS X as your Java development platform.

Java Development Tools

Installing the JDK

It is pre-installed.  The version you get depends on the version of OS X you have installed.  I’m lucky and only need Java 1.6 right now so I haven’t had to deal with the concurrent Java versions problems that don’t seem to be going away any time soon; however, there is no free lunch in software development.  The system JDK does not come with src.jar, nor should you probably go mucking around in there customizing the endorsed directory or other common developer tweaks.

Since the bundled JVM isn’t the blessing it initially appears to be, I ended up downloading the JDK again from Apple at http://connect.apple.com.  This site requires registration.  You can register for free as a “Registered Apple Developer”.  This may not be immediately obvious as most pages only mention the paid options.  Got to http://developer.apple.com/programs/register/ to create your account and then go back to connect.apple.com to download a JDK for your version of OS X.  This JDK will install in /Library/Java/JavaVirtualMachines instead of /System/Library/Java/JavaVirtualMachines.  This JDK also comes with src.jar.  You will want to use this JDK in Eclipse or associate its src.jar with the JARs in the bundled JDK if they are the same version and you don’t want to use the self-installed JDK for some reason.

Looking at the JDK files

Java installations on OS X are packaged in what appears as a file ending with .jdk in Finder.  If you right-click in Finder and select “Show Package Contents”, you can get at the guts of the installation in Finder.  The .jdk “file” is just a directory and you can navigate to it and through it in the shell without issue.  The typical folder structure you see on Windows is located in the Contents/Home folder inside of the .jdk “file”.  This is the path you would point Eclipse to when adding a JDK.  Note that you will likely need to paste the path into Eclipse because the Java file browser wouldn’t navigate into the .jdk file when I tried to do it that way.  Just paste the complete path into Eclipse, for example /Library/Java/JavaVirtualMachines/1.6.0_22-b04-307.jdk/Contents/Home.

Picking the default Java version

In general, this is controlled by the Java Preferences application located in /Applications/Utilities.  You can launch it from the Dock or from a shell with the following command

open /Applications/Utilities/Java\ Preferences.app/

By the way, applications in OS X appear as a .app file.  Just like the .jdk file, they are really a directory that appears as a file in Finder.  You can view the contents in Finder the same way you would view the contents of a .jdk file.  There are other, more brute force approaches to changing the Java version, but I thankfully haven’t had to use them.  I can’t comment on how well they work so I won’t include a discussion of them here.

Maven and Ant

Maven and Ant were pre-installed on my OS X 10.6 installation.  The pre-installed versions I got thankfully aligned with the versions I am currently using for development so I haven’t needed to mess with either of these yet.

IDEs

I primarily use Eclipse these days.  Just download extract and run Eclipse.app.  Install your regular plug-in set and you are on your way to developing in Java on OS X.  I cover installing Subclipse in the version control section later in the article.

General Tools

• Instant Messaging (AIM, Jabber, etc.) – I was using Pidgin so Adium was the natural choice on OS X.  I have been very happy with it so far.
• IRC – I was using X-Chat on Windows and found that it did what I needed it to do.  There is a X-Chat Aqua for OS X; however, I found its notification configuration to be a bit daunting.  I don’t watch the chat traffic unless I get mentioned and I found that Colloquy made it very straight forward to configure notifications.  If you play with the themes a little you can also configure the layout to mimic X-Chat or mIRC.
• New Feeds / RSS – I was using FeedDemon on Windows.  NetNewsWire comes close to the feature set of FeedDemon with Google Reader integration, but it currently lacks OAuth support so you can’t use it to read your Twitter stream.
• SSH / Putty – OS X, being all unix like, has SSH already available from the shell.  One thing I liked about Putty was that it was easy to store configurations for server names, tunnels, etc.   JellyFiSSH provides a nice session management GUI over the ssh program.
• File Transfer / SCP/ SFTP – On Windows, I found WinSCP to provide a nice GUI for managing files on a remote system.  In OS X, Cyberduck provides the same features and more.
• Task Manager – The OS X equivalent is called Activity Monitor.  It is in /Applications/Utilities.  Activity Monitor provides everything that was available in Task Manager and a lot more.  This is a nice GUI alternative to using ps in a shell.
• Multiple Monitor Utilities – On Windows I’ve used a number of tools over the years to mimic Exposé/Spaces and to put a fully functional task bar on my second monitor.  Exposé and Spaces are part of OS X; however, I found it annoying to have to go back to the primary monitor any time I wanted to use a menu in a program.  SecondBar clones most of the primary menu bar and lets you move it wherever you want.  Sometimes it gets out of synch with the current app and you have to switch focus from the app and back again to update it.  Otherwise, it does what I want.
• Archive File / WinZip – While later versions of Windows have built-in support for .zip files, WinZip was great for opening .jar files and doing more advanced archival operations.  OS X has native support for archives; however, this support only seems to include the ability to make them and extract them in their entirety.  Zipeg allows you to explore a number of archive formats and extract portions.  Zipeg does not provide Quick Look support though nor does it have every feature under the sun.  BetterZip, a commercial application, has more features than Zipeg but will cost you $20.  As I mentioned earlier, I am a big fan of free, so I use the free BetterZip Quick Look Generator for quick look support and Zipeg when I actually need to dig into an archive and muck around.
• Text Editing / Notepad++ – On Windows I loved Notepad++ and the many plug-ins available for it.  I do a lot of work with XML messages and output files so something with tabs, syntaxt highlighting, and compare/diff support is critical.  On the free front, TextWrangler gets the job done.  Since a lot of the XML I work with is not formatted for human consumption, the ability to pretty print XML is a must have.  Text Wranger does not have this capability out of the box, but it can integrate with shell scripts to get the job done.
• Open Command Here – On Windows, the Open Command Here Power Toy was a life saver. Ever need a shell opened to a folder you were browsing in Explorer?  This little context menu addition made it a snap.  There are a number of Finder droplets that will perform this action in OS X; however, I prefer the action to reside in the context menu and I couldn’t stand how the droplets interpreted the root folder in list view as the current folder even when I highlighted another folder.  Open Terminal Here Service to the rescue.  This one places the entry in the context menu and works with the folder you right-clicked on.

Version Control

Subversion

On Windows, TortoiseSVN coupled with the command line tools and svnmerge covered my needs.  Svnmerge is written in Python and transitions to OS X without a hitch, unfortunately, there is no full featured free alternative to TortoiseSVN.  I got close enough using a combination of the following tools:

1. Subclipse – The fantastic Eclipse plug-in that you should be using even if you aren’t on OS X.
2. Subversion – Aside from being the easiest way to get Subclipse working, this also provides the rest of Subversion in binary form.
3. SvnX – Not quite TortoiseSVN; however, it does have a repository browser and support for working with local Subversion working copies.  This is a nice tool when you don’t want to fire up Eclipse just to browse a remote repository.
4. SCPlugin – This aims at providing TortoiseSVN like features for OS X, but is still way too immature to make the comparison. The directory icons don’t work in OS X 10.6; however, the Finder droplet does work and provides a quick way to do simple SVN commands in Finder until you are ready to just move completely to the command line.  This one will likely be removed in the next couple weeks as I don’t use it often.

Git

I was not a big Git user on Windows; however, everyone seems to be in a love affair with Git so I will cover it here.  My Git environment on OS X is as follows:

1. EGit – This is like Subclipse, but for Git.
2. Git – This provides the command line tooling for Git.
3. GitX – GitX provides a polished GUI when compared to the GUI bundled with the Git tooling and also provides a GUI for helping you to stage files for a commit.  There is some overlap with what EGit provides, but as with TortoiseSVN and SvnX, it is nice to have a tool outside of Eclipse sometimes.
4. OpenInGitX – Not the context menu item I long for, but it does provide a droplet for Finder that allows you to launch GitX on a folder from the Gui.

Things that OS X just doesn’t make easy

Closing the lid without going to sleep

Every time you close the lid, OS X puts the laptop to sleep.  I really hate this because I often move around in the same building and I don’t want all of my network connection to time out when I do.  Digging out key fobs to reconnect to a VPN and finding that the 600MB .iso download died gets old fast.  InsomniaX lets you shut the lid without putting the machine to sleep.

Locking the laptop without logging out

You don’t want to log out and close all of your running applications every time that you need to get a drink, stretch your legs, or go to the bathroom.  I’ve found two main ways to deal with this.

1. If you have the system configured to lock the laptop when resuming from screensaver/screen blank, you can press Shitf-Control-Eject to turn off the monitor.  The machine will lock after the grace period defined in your system preferences.
2. You can enable fast user switching or use any of the couple other methods outlined here.

Setting environment variables for shell and GUI applications

For the shell, you can simply use any of the well-known ways to set environment variables.  But what do you do if your GUI application requires the variables too.  OS X stores variables in ~/.MacOSX/environment.plist (note you won’t be able to see this in Finder by default and you will probably have to create it yourself).  Plist files are XML files these days, but it helps to have an editor.  There is an editor in the XCode bundle, but that is 650MB that expands to several GBs of stuff that you probably won’t use a lot.  Pref Setter is a lightweight editor for .plist files that also shows you many of the .plist files on your system that are waiting for you to tweak.  This article discusses creating an environment.plist file.  Keep in mind that you will need to log out and back in before the changes take place.

Showing hidden files in Finder

Finder doesn’t show you hidden file.  Finder doesn’t have an accessible configuration option to show you hidden files.  Finder drives me crazy most of the time.  With this tip, you can bend Finder to your will and hopefully stay sane a little longer.  From a shell, you can execute the following commands to enable how and hide hidden files in Finder, respectively.

defaults write com.apple.Finder AppleShowAllFiles TRUE

defaults write com.apple.Finder AppleShowAllFiles FALSE

After making this change, you will need to restart finder.  You can do that by option clicking on Finder in the dock and selecting relaunch.  I wrote a simple shell script that sets the property and put it in a folder on the path.  This makes it simple to run the script from anywhere in a shell, although I don’t think I have turned hiding back on for weeks now.

Setting the title of a Terminal window

I usually have more than one Terminal window open and often I have a couple tabs in each window.  With so many sessions open and nothing really differentiating between them visually in Exposé, I find it nice to name the windows/tabs for easy identification.  In Windows, the title command allowed you to easily set the window title.  The following command will change the title of the Terminal window or tab.

echo -n -e "\033]0;<YOUR_TITLE_HERE>\007"

That is a lot to remember so I recommend replacing <YOUR_TITLE_HERE> with $1 and putting this in a script named title.  Put the script on the path and you can execute

title <YOUR_TITLE_HERE>

from anywhere in a shell.

Opening two instances of the same application

Click on the alias or the .app file as many times as you like, OS X isn’t going to do it.  I often run two copies of Eclipse, one for stuff I am working on related to this blog or an open source project, and another with client code.  I switch back and forth and don’t always want to close one instance and lose its current state.  My machine has 8GB of memory so it really doesn’t care if I leave another copy of Eclipse running all day on another screen.  You can launch a separate instance of Eclipse from the shell using the following command.

open -n <PATH_TO_APP_FILE>

How Trash works on your hard disk and on removable media

This article explains how Trash works in general and on removable media of varying types.  I was a little surprised when I deleted a file off of a thumb stick only to find that the stick was still full because the file ended up in the trash folder on the thumb stick.  Give the article a read so you know what to expect.

Things I haven’t figured out yet

The following is a short list of stuff that I wish worked or for which I haven’t yet found a way around.

1. Native VPN client support for split DNS.  Support for this configuration in OS X 10.6 is just broken.
2. Finder kills me sometimes.  I wish it had tabs, dual view, or at the very least a folder tree view like Explorer did in Windows.  I’ve seen a number of commercial add-ons or replacements, but haven’t tried any yet.
3. A “move to other monitor and resize proportional” button in the title bar of windows.  UltraMon had this in Windows and I found it very useful since I have my external monitor in portrait orientation and windows moved from one monitor are often inappropriately sized on the other.
4. Deleting something from Finder without going through the trash first, as with shift-delete in Windows.  I’ve seen a number of scripts, but I haven’t been brave enough to try any yet.

If anyone has recommendations for these unresolved items, or suggestions relating to any of the things mentioned in this article, leave a comment and I will check it out.

This article builds on the setup described in my previous article Using NSS for FIPS 140-2 compliant transport security in CXF by adding a WS-Security compliant digital signature over portions of the message as well as using WS-Security to encrypt portions of the message.  Refer to my previous post for details on FIPS and configuring NSS in Java.

These same features are also available in FUSE Services Framework, a freely distributed  enterprise ready distribution of CXF available with various subscription options.

It all worked in the article about NSS, TLS, and FIPS, does it all just work with WS-Security too?

In short, no.  There are a couple of important aspects/features/limitations of the Sun PKCS#11 provider that prevents things from just working with WSS4J and NSS in all cases.  If you are using NSS as the key store, any case where WSS4J needs to resolve a public certificate in the key store that is not paired with a private key causes issues.

The rundown of what works and what doesn’t work is as follows:

1. Creating signatures with an embedded security token (e.g. an embedded BinarySecurityToken containing an X509 certificate) works
2. Verifying signatures with an embedded security token (e.g. an embedded BinarySecurityToken containing an X509 certificate) works
3. Creating signatures with an external security token (e.g. an Issuer Serial reference to an X509 certificate) reference works
4. Verifying signatures with an external security token reference (e.g. an Issuer Serial reference to a X509 certificate) does not work
5. Creating encrypted content that uses the public part of an asymmetric key pair to conceal a symmetric key does not work
6. Verifying encrypted content works

The reason some of the above scenarios don’t work has to do with the Sun PKCS#11 provider and how it interacts with end-user certificates in the NSS database.  That is, certificates that are not paired with a private key and are not a CA certificate.

Item 4 in Appendix B of the PKCS#11 guide states:

Each certificate not part of a private key entry (as the end entity certificate) is checked whether it is trusted. If the CKA_TRUSTED attribute is true, then a KeyStore trusted certificate entry is created with the CKA_LABEL value as the KeyStore alias. If the certificate has no CKA_LABEL, or if multiple certificates share the same CKA_LABEL, then the alias is derived as described above.If the CKA_TRUSTED attribute is not supported then no trusted certificate entries are created.

This statement would indicate that in the ideal case, an alias will be added to the Java KeyStore object for each “trusted” certificate in the NSS database.  In practice, when using the NSS provider in FIPS mode, any end-user certificate that is not paired with a private key in the database and is not a CA certificate, will be excluded from the listed aliases in the Java KeyStore.  Consequently, WSS4J will not be able to perform the needed certificate look up for verification of externally referenced security tokens using the NSS provided key store.  If you need support for this type of token reference, the only option is to extend  WSS4J’s org.apache.ws.security.components.crypto.Merlin class or one of its ancestors to provide an alternate mechanism for resolving external security token references.  This is not a bug in CXF, WSS4J, or NSS.  NSS exposes the trusted end-user certificates to the JVM.  It is the Sun PKCS#11 provider that chooses not to expose the end-user certificates through the created Java KeyStore.

Putting it all together – Setting up NSS, the JVM, WSS4J, and CXF

Quick Links

This section contains a single location for links to the major resources mentioned in the Putting it all together section.

• Explanation of FIPS and how to configure NSS in the JVM – Using NSS for FIPS 140-2 compliant transport security in CXF
• Example Source Code SVN Location – https://davidvaleri.googlecode.com/svn/projects/examples/cxf-wss-fips/tags/cxf-wss-fips-1.0
• WS-Security Specification – http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf

Setting up NSS and setting up the JVM

Read the sections titled Setting up NSS and Setting Up the JVM in my previous post about NSS.

Setting up WSS4J

CXF uses the WSS4J library to provide WS-Security operations over SOAP messages.  WSS4J provides configuration options that allow for the use of custom key store providers as well as algorithm sources.  By default, WSS4J installs the Bouncy Castle provider and the JuiCE provider if they are available on the classpath.  As Bouncy Castle is not a FIPS approved crypto implementation, the first step to achieving compliance is to remove the provider JAR from the class path.  The following XML fragment excludes the Bouncy Castle artifact from the Maven 2 transitive dependency resolution process.

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-ws-security</artifactId>
  <version>${cxf.version}</version>
  <scope>runtime</scope>
  <exclusions>
    <exclusion>
      <groupId>org.bouncycastle</groupId>
      <artifactId>bcprov-jdk15</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Once Bouncy Castle is off the class path, the built-in provider can still provide algorithm implementations for some algorithms used by WSS4J.  If you are not replacing the built-in provider, WSS4J needs to be configured to retrieve its algorithm implementations from a specific provider.  The following code fragment demonstrates how to configure the provider that WSS4J will use.

JCEMapper.setProviderId("SunPKCS11-nss-client");

Line 1 in the above code fragment sets the provider name used by WSS4J when retrieving algorithm implementations.  The provider name specified is derived from the name property in the PKCS#11 configuration file that loads NSS into the JVM.  Refer to my earlier blog post for details on the contents of this file.

The configuration options above direct WSS4J to use the proper provider for retrieving algorithm implementations; however, we still need to configure WSS4J to use the NSS PKCS#11 provider as a key and trust store.  The following XML fragment represents the WSS4J configuration properties needed to use the NSS key store.

<!-- Define a Properties object with the properties required by the
 org.apache.ws.security.components.crypto.Merlin WSS4j Crypto implementation.
 This crypto config is used for signature creation and validation. -->
<util:properties id="signatureProperties">
  <!-- Defines the implementation class. -->
  <prop key="org.apache.ws.security.crypto.provider">org.apache.ws.security.components.crypto.Merlin</prop>
  <!-- Defines the location, on the classpath, of the keystore file.  Also
       takes URL or file path. Not applicable when using PKCS 11. -->
  <!-- <prop key="org.apache.ws.security.crypto.merlin.file"></prop>  -->
  <!-- The type of the keystore pointed to by org.apache.ws.security.crypto.merlin.file. -->
  <prop key="org.apache.ws.security.crypto.merlin.keystore.type">PKCS11</prop>
  <!-- The crypto provider that can load the keystore. -->
  <prop key="org.apache.ws.security.crypto.merlin.keystore.provider">SunPKCS11-nss-client</prop>
  <!-- The password for the keystore file. -->
  <prop key="org.apache.ws.security.crypto.merlin.keystore.password">Password12345!</prop>
  <!-- The alias for the default private key to use.  Not required.
  <prop key="org.apache.ws.security.crypto.merlin.keystore.alias"></prop> -->
  <prop key="org.apache.ws.security.crypto.merlin.cert.provider"></prop>
  <!-- If the JVM cacerts file contents should be loaded into the trust chain. -->
  <prop key="org.apache.ws.security.crypto.merlin.load.cacerts">false</prop>
  <!-- If the JVM cacerts file is used, the password for the file.
  <prop key="org.apache.ws.security.crypto.merlin.cacerts.password"></prop> -->
</util:properties>

• Line 11 – This line indicates that WSS4J should use a PKCS#11 provider for its key store.
• Line 13 – This line indicates the PKCS#11 provider name used to provide the key store.  This name matches with the name provided in the PKCS#11 configuration file used to load NSS.
• Line 15 – This line provides the password needed to access the key store.

Running the example code

To run the example code you must have the following:

1. Maven 2.2.1
2. Java 1.6
3. NSS 3.12.4

To run the example, you must first install or build NSS.  Get the binary or source distribution from the Mozilla FTP server and follow the instructions above for configuring the needed environment variables.

Create an environment variable named “NSS_HOME” and set its value to be the path to the directory containing the NSS libraries.  The example project uses this environment variable to locate your NSS installation directory and generate configuration files for the PKCS#11 provider for you.

Next, checkout the code from https://davidvaleri.googlecode.com/svn/projects/examples/cxf-wss-fips/tags/cxf-wss-fips-1.0 using a subversion client of your choice.

From the checkout folder, use a shell to execute:

 mvn -P server

From the checkout folder, use another shell to execute:

mvn -P client

The server log output is written to the file at target/surefire-reports/valeri.blog.examples.cxf_wss_fips.CustomerServiceRunner.out

Additional Options

• You can enable JSSE log output by adding -Djsse.debug=all to either of the commands above.
• You can modify the log output to contain more details by editing the log4j.properties file in src/test/resources.
• You can access the service WSDL at https://localhost:8443/services/CustomerService?wsdl using a Web browser.  You will want to add the example’s CA certificate to your browser’s trust store and add the client’s identity to your client’s key store.  The .crt and .pk12 files, as well as JKS files that contain these certificates and keys are available in src/test/resources.  The password for these files is “password”.  Note that you should remove the example CA from your browser when finished to avoid a potential security threat.  The example CA key used here is available in the Subversion repository and could be used by anyone to generate additional client or server certificates for malicious purposes.  Leaving the CA in your browser’s trust store leaves you vulnerable.

What else should I know?

1. If you are this concerned about cryptographic operations, You really should be running a security manager to prevent application code from altering the container JVM’s security configuration.
2. You may be required to remove additional non-FIPS validated providers from the JVM to meet accreditation guidelines.
3. This is just an example and I am not claiming that it will be 100% in-line with your security requirements.

Update: At the publishing of this article, PKCS#11 support within CXF’s HTTP/Jetty transports was only available in snapshot releases of 2.4 and 2.3.1.  Now that CXF 2.3.1 has been released, the examples in this post have been updated to use CXF 2.3.1.  This capability also appears in FUSE Services Framework.

What is this FIPS thing?

FIPS, or the Federal Information Processing Standards, is a collection of documents published by the National Institute of Standards and Technology (NIST) providing guidance on range of computer and telecommunications related topics and standards.  FIPS publication 140-2, Security Requirements for Cryptographic Modules, deals specifically with cryptography related standards.  Along with the requirements dictated by the publication, there is also the Cryptographic Module Validation Program (CMVP) which certifies cryptography modules against the FIPS 140-2 requirements.  You can see a list of vendors with validated modules at http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401vend.htm.  Stated simply, FIPS 140-2 compliant TLS requires using a limited set of algorithms and a validated implementation of said algorithms.

So what is the rub?

This is all fine and well if you have a hardware cryptography device, an application server, and/or a commercial software library that provides a FIPS 140-2 validated cryptography module.  But what if, on the off chance, you are working on a project with no budget or you don’t have one of the aforementioned solutions?  Therein lies the rub.

Java and NSS to the rescue

Starting in Java 5, several changes to the cryptographic APIs made it possible to have a Java application interact with tokens and algorithms provided through PKCS#11, the Cryptographic Token Interface Standard.  For more details about the use of the Sun PKCS#11 provider and how to interact with PKCS#11 tokens/algorithms, refer to the Java PKCS#11 Reference Guide.  But JVM PKCS#11 support is only half of the equation.  In order to be FIPS 140-2 compliant, we still need a PKCS#11 implementation that has been through the CMVP.  This is where Network Security Services (NSS) comes in.  NSS is a PKCS#11 compliant cryptographic library from Mozilla that also happens to have passed through the CMVP.  NSS is distributed under the GPL, LGPL, and the MPL.  You can view the CMVP information for NSS on the NIST  Web site.

Putting it all together – Setting up NSS, the JVM, JSSE, and CXF

Quick Links

This section contains a single location for links to the major resources mentioned in the Putting it all together section.

• NSS Source and Binary Download – ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_4_RTM/
• NSS Utility Documentation – modutil, certutil, and pk12util
• Example Source Code SVN Location – https://davidvaleri.googlecode.com/svn/projects/examples/cxf-tls-fips/tags/cxf-tls-fips-1.0
• Java PKCS#11 Reference Guide – Java PKCS#11 Reference Guide

Setting up NSS

The first step in putting all the pieces together is to configure NSS.  NSS is a native library which means you will either need to compile it from source or download a compiled binary for your platform.  The latest version to appear in the NIST CMVP list is 3.12.4.  You can find compiled binaries and source for 3.12.4 at ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_12_4_RTM/.

Once you have built the binaries, or extracted them from the downloaded archive, you will want to 1) add the NSS libraries to the LD_LIBRARY_PATH or PATH environment variable depending on your operating system and 2) add the NSS utilities to the PATH environment variable.  Once installed, you will use the modutil, certutil, and pk12util utilities to create a database and populate it with key information.  Note that NSS can also be used purely as an algorithm provider without a database.  Refer to the Java PKCS#11 Reference Guide for more details on alternative usage modes.

The following sequence of commands illustrates how to create the database, enable FIPS compliance, and populate the database with some certificates and keys.

1. modutil -create -dbdir ./client

2. modutil -fips true -dbdir ./client

3. modutil -changepw "NSS FIPS 140-2 Certificate DB" -dbdir ./client

4. certutil -A -d ./client -t "TCu,,TCu" -n "Test CA 1" -i ./pki/test-ca-1.crt

5. pk12util -i ./pki/test-user-1.p12 -n test-user-1 -d ./client

Command 1 creates a new database in the client directory relative to where the command is executed.  Command 2 enables FIPS compliant mode in the database.  Command 3 changes the password of the FIPS token.  Keep in mind that there are password complexity requirements when FIPS mode is enabled and that the utility will simply report that it was unable to set the password when these minimum complexity requirements are not met.  Command 4 imports a CA certificate into the database under the alias “Test CA 1″ and sets the trusted usages for the certificate.  Command 5 imports a private key and certificate into the database under the alias “test-user-1″.  This sequence of commands can be used to create and populate a database for use on a client or server.  The resulting database can be seen in the example source code in the src/test/pkcs11/client folder.  The password for the database is “Password12345!”.

Setting up the JVM

Once NSS is installed and an NSS database exists for your client/server, the next step is to configure a JVM to use it.  Java 1.6 provides great support for NSS and will be used exclusively in this example.  One may configure a PKCS#11 provider in the JVM dynamically at runtime or statically in the JVM configuration files.  We will explore both approaches.

Before we can create a PKCS#11 provider in the JVM, we must first create a configuration file for the provider.  The configuration file is a simple text file containing key-value pairs for the relevant configuration options.  There are many options described in the Java PKCS#11 Reference Guide, but this example only needs to use a few.  The example configuration below provides a name for the provider, the location of the library files for NSS and the path to the database that was created earlier.

name = nss-client
nssLibraryDirectory = /path/to/nss/lib
nssSecmodDirectory = /path/to/db/dir

Dynamic configuration is performed using the static utility methods of java.security.Security.  The following code fragment from the example source code illustrates how to add the PKCS#11 provider and to reconfigure the Java Secure Socket Extension (JSSE) provider to leverage the PKCS#11 provider for FIPS compliant operations.  Note that this code works on the Sun JVM.  Your mileage will vary if you use a different JSSE provider in your JVM or a non-Sun JVM.

Provider nss = new sun.security.pkcs11.SunPKCS11(configFile);
Security.addProvider(nss);

int sunJssePosition = -1;
int currentIndex = 0;
for (Provider provider : Security.getProviders()) {
    if ("SunJSSE".equals(provider.getName())) {
        sunJssePosition = currentIndex + 1;
        break;
    }

    currentIndex++;
}

Security.removeProvider("SunJSSE");

Provider sunJsse = new com.sun.net.ssl.internal.ssl.Provider(nss);
if (sunJssePosition == -1) {
    Security.addProvider(sunJsse);
}
else {
    Security.insertProviderAt(sunJsse, sunJssePosition);
}

The constructor on line 1 creates an instance of the PKCS#11 provider using the configuration file specified by the configFile variable.  This variable represents the file system path to the NSS configuration file described earlier.  Note that the above code must be executed before any network connections using JSSE are established and that the above code requires the correct permissions when a security manager is in place.  For these reasons, dynamic configuration should usually be avoided when running inside of a container or framework such as OSGi and JEE.  Note that the example that accompanies this article uses dynamic configuration simply to reduce the amount of setup required to run the example.

Static configuration is possible at the JVM level.  The $JAVA_HOME/lib/security/java.security file contains definitions of the providers that will be started with the JVM.  The file will have a section resembling the following example.

security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=com.sun.security.sasl.Provider
security.provider.7=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.8=sun.security.smartcardio.SunPCSC
security.provider.9=sun.security.mscapi.SunMSCAPI

To enable the PKCS#11 provider and reconfigure the JSSE provider, change the configuration file to resemble the following.

security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=com.sun.net.ssl.internal.ssl.Provider SunPKCS11-nss-client
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=com.sun.security.sasl.Provider
security.provider.7=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.8=sun.security.smartcardio.SunPCSC
security.provider.9=sun.security.mscapi.SunMSCAPI
security.provider.10=sun.security.pkcs11.SunPKCS11 /path/to/nss/config/file

In the above example, the last line adds the PKCS#11 provider with the appropriate configuration file while the third line configures the JSSE provider to use the PKCS#11 provider for cryptographic operations.  The value “SunPKCS11-nss-client” was created by concatenating “SunPKCS11-” with the value of the name property from the PKCS#11 configuration file.  In the example configuration file above, the name is nss-client, resulting in the provider name “SunPKCS11-nss-client”.

Configuring the CXF HTTP Transport

For the server-side configuration, we will be using the PKCS#11 provider with the name configuration attribute of “nss-server”.  The configuration uses the CXF Jetty Transport’s Spring namespace handler for configuration.  More details about this configuration mechanism can be found in the CXF Jetty Transport documentation.  The relevant lines are described after the following XML fragment.  Click here to view this fragment in context.

<!-- Define the Jetty HTTP server configuration for the CXF bus. -->
<httpj:engine-factory bus="cxf">
  <httpj:identifiedTLSServerParameters id="secure">
    <httpj:tlsServerParameters secureSocketProtocol="TLS">
      <sec:clientAuthentication required="true" want="true"/>
      <!-- Define the keystore for the server identity as a classpath resource.
           In a production system, these properties would be encrypted/obfuscated using
           a library such as Jasypt (http://www.jasypt.org/) and Spring's property placeholder
           capabilities. -->
      <sec:keyManagers>
        <sec:keyStore type="PKCS11" provider="SunPKCS11-nss-server" password="Password12345!"/>
      </sec:keyManagers>
      <sec:trustManagers>
        <!-- In a production system, these properties would be encrypted/obfuscated using
             a library such as Jasypt (http://www.jasypt.org/) and Spring's property placeholder
             capabilities. -->
        <sec:keyStore type="PKCS11" provider="SunPKCS11-nss-server" password="Password12345!"/>
      </sec:trustManagers>
      <sec:cipherSuitesFilter>
        <sec:include>SSL_RSA_WITH_3DES_EDE_CBC_SHA</sec:include>
        <sec:include>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</sec:include>
        <sec:include>TLS_RSA_WITH_AES_128_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</sec:include>
        <sec:include>TLS_RSA_WITH_AES_256_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</sec:include>
        <!-- The suites below have been disabled due to
             http://bugs.sun.com/view_bug.do?bug_id=6763530 -->
        <!-- <sec:include>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</sec:include>  -->
        <!-- <sec:include>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</sec:include> -->
      </sec:cipherSuitesFilter>
    </httpj:tlsServerParameters>
  </httpj:identifiedTLSServerParameters>
  <!-- Define the HTTPS port, crypto configuration, and other properties. -->
  <httpj:engine port="8443">
    <httpj:tlsServerParametersRef id="secure" />
    <httpj:threadingParameters minThreads="5" maxThreads="15" />
  </httpj:engine>
</httpj:engine-factory>

• Line 4 – This line’s secureSocketProtocol attribute identifies TLS as the desired protocol.  TLS is the only protocol available when in FIPS mode.
• Line 5 – This line specifies that mutual authentication is required.  Not all secure HTTP connections need to use mutual authentication, but this example uses it to demonstrate configuring a key store on the client side as well as on the server side.
• Line 11 – This line specifies the type of key store in use and how to access it for the server’s identity.  Typically you use a JKS file, but in this example we are using the NSS database accessed through the PKCS#11 provider configured against the NSS database.  Note the provider name identifies the PKCS#11 provider configuration we created for the server NSS database.
• Line 18 – This line specifies the type of key store in use and how to access it for the server’s trust configuration.  Typically you use a JKS file, but in this example we are using the NSS database accessed through the PKCS#11 provider configured against the NSS database.  Note the provider name identifies the PKCS#11 provider configuration we created for the server NSS database.
• Line 21 – This line and the nested XML content identifies a white list of cipher suites that will be enabled if available.  When configured the JSSE is configured against NSS operating in FIPS mode, only FIPS approved cipher suites will be available; however, some cipher suites trigger issues with the PKCS#11 support in the JVM and are disabled for compatibility reasons.  This configuration is shown as a white list, but could just as easily be configured as a black list using the <sec:exclude> element.

For the client-side configuration, we will be using the PKCS#11 provider with the name configuration attribute of “nss-client”.  The configuration uses the CXF HTTP Transport’s Spring namespace handler for configuration.  More details about this configuration mechanism can be found in the CXF HTTP Transport documentation.  The relevant lines are described after the following XML fragment.  Click here to view this fragment in context.

<!-- Define the HTTP client configuration for all target service invocations. -->
<http:conduit name="*.http-conduit">
  <!-- Define the SSL info for the client connections. -->
  <http:tlsClientParameters secureSocketProtocol="TLS">
    <!-- Defines the identity info for the client's connection. -->
    <sec:keyManagers>
      <!-- In a production system, these properties would be encrypted/obfuscated using
           a library such as Jasypt (http://www.jasypt.org/) and Spring's property placeholder
           capabilities. -->
      <sec:keyStore type="PKCS11" provider="SunPKCS11-nss-client" password="Password12345!" />
    </sec:keyManagers>
    <!-- Defines the trust info for the client's connection. -->
    <sec:trustManagers>
      <!-- In a production system, these properties would be encrypted/obfuscated using
           a library such as Jasypt (http://www.jasypt.org/) and Spring's property placeholder
           capabilities. -->
      <sec:keyStore type="PKCS11" provider="SunPKCS11-nss-client" password="Password12345!" />
    </sec:trustManagers>
    <sec:cipherSuitesFilter>
        <sec:include>SSL_RSA_WITH_3DES_EDE_CBC_SHA</sec:include>
        <sec:include>SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA</sec:include>
        <sec:include>TLS_RSA_WITH_AES_128_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_DSS_WITH_AES_128_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</sec:include>
        <sec:include>TLS_RSA_WITH_AES_256_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_DSS_WITH_AES_256_CBC_SHA</sec:include>
        <sec:include>TLS_DHE_RSA_WITH_AES_256_CBC_SHA</sec:include>
        <!-- The suites below have been disabled due to
             http://bugs.sun.com/view_bug.do?bug_id=6763530 -->
        <!-- <sec:include>TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_RSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_RSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</sec:include>  -->
        <!-- <sec:include>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_anon_WITH_AES_128_CBC_SHA</sec:include> -->
        <!-- <sec:include>TLS_ECDH_anon_WITH_AES_256_CBC_SHA</sec:include> -->
      </sec:cipherSuitesFilter>
  </http:tlsClientParameters>
  <http:client Connection="Keep-Alive" />
</http:conduit>

• Line 4 – This line’s secureSocketProtocol attribute identifies TLS as the desired protocol.  TLS is the only protocol available when in FIPS mode.
• Line 10 – This line specifies the type of key store in use and how to access it for the client’s identity.  Typically you use a JKS file, but in this example we are using the NSS database accessed through the PKCS#11 provider configured against the NSS database.  Note the provider name identifies the PKCS#11 provider configuration we created for the client NSS database.  Note that the key manager configuration is not necessary on clients not using mutual authentication.
• Line 18 – This line specifies the type of key store in use and how to access it for the client’s trust configuration.  Typically you use a JKS file, but in this example we are using the NSS database accessed through the PKCS#11 provider configured against the NSS database.  Note the provider name identifies the PKCS#11 provider configuration we created for the server NSS database.
• Line 21 – This line and the nested XML content identifies a white list of cipher suites that will be enabled if available.  When configured the JSSE is configured against NSS operating in FIPS mode, only FIPS approved cipher suites will be available; however, some cipher suites trigger issues with the PKCS#11 support in the JVM and are disabled for compatibility reasons.  This configuration is shown as a white list, but could just as easily be configured as a black list using the <sec:exclude> element.

Running the example code

To run the example code you must have the following:

1. Maven 2.2.1
2. Java 1.6
3. NSS 3.12.4

To run the example, you must first install or build NSS.  Get the binary or source distribution from the Mozilla FTP server and follow the instructions above for configuring the needed environment variables.

Create an environment variable named “NSS_HOME” and set its value to be the path to the directory containing the NSS libraries.  The example project uses this environment variable to locate your NSS installation directory and generate configuration files for the PKCS#11 provider for you.

Next, checkout the code from https://davidvaleri.googlecode.com/svn/projects/examples/cxf-tls-fips/tags/cxf-tls-fips-1.0 using a subversion client of your choice.

From the checkout folder, use a shell to execute:

 mvn -P server

From the checkout folder, use another shell to execute:

mvn -P client

The server log output is written to the file at target/surefire-reports/valeri.blog.examples.cxf_tls_fips.CustomerServiceRunner.out

Additional Options

• You can enable JSSE log output by adding -Djsse.debug=all to either of the commands above.
• You can modify the log output to contain more details by editing the log4j.properties file in src/test/resources.
• You can access the service WSDL at https://localhost:8443/services/CustomerService?wsdl using a Web browser.  You will want to add the example’s CA certificate to your browser’s trust store and add the client’s identity to your client’s key store.  The .crt and .pk12 files, as well as JKS files that contain these certificates and keys are available in src/test/resources.  The password for these files is “password”.  Note that you should remove the example CA from your browser when finished to avoid a potential security threat.  The example CA key used here is available in the Subversion repository and could be used by anyone to generate additional client or server certificates for malicious purposes.  Leaving the CA in your browser’s trust store leaves you vulnerable.

What else should I know?

1. If you are this concerned about cryptographic operations, You really should be running a security manager to prevent application code from altering the container JVM’s security configuration.
2. You may be required to remove additional non-FIPS validated providers from the JVM to meet accreditation guidelines.
3. This is just an example and I am not claiming that it will be 100% in-line with your security requirements.

WS-Addressing Headers

WS-Addressing conveys WS-Addressing message addressing properties (MAPs) in a SOAP Header.  These properties can affect the processing of the message and where/how the response message is sent.  The MAPs and their corresponding XML infoset are defined in section 3 of the WS-Addressing 1.0 – Core specification.  The use of MAPs in a SOAP envelope are described by the WS-Addressing 1.0 – SOAP Binding specification.  Finally, the requirements for the inclusion of the MAPs in the messages of a WSDL defined service are defined in section 5 of the WS-Addressing 1.0 – WSDL Binding specification.  It is the default values assigned to a MAP in the core specification and the variation in required MAPs for a given WSDL MEP as defined in the WSDL binding specification that combine to create the subtle variances in the presence of the header elements in any given message.  This variance alone does not typically cause any issues unless you are trying to configure WSS4J to sign these header elements.

The Signing Problem

When configuring CXF without the help of WS-SecurityPolicy (WS-SP), the list of message elements to be signed is set as a configuration option on the WSS4J out interceptor.  The following code fragment illustrates a typical WSS4J configuration in CXF using CXF’s Spring integration.

<!-- Configure the outbound WSS4J interceptor. -->
<bean id="wss4jOutInterceptor">
  <constructor-arg>
    <!-- The entry keys in this map are defined in
         org.apache.ws.security.handler.WSHandlerConstants
         but are referenced as String literals here for brevity over
         the use of the util:constant element. -->
    <map>
      <entry key="action" value="Timestamp Signature" />
      <!-- This is the fallback user for sig/enc if the sig/enc specific
           properties are not set.  WSS4JOutInterceptor looks for it
           and fails if it is not set. -->
      <entry key="user" value="test-service-1 (test-ca-1)" />

      <!-- Timestamp TTL in seconds. -->
      <entry key="timeToLive" value="60" />

      <!-- The certificate alias in the signature crypto config to sign
           the message with.  The password is retrieved from the callback handler. -->
      <entry key="signatureUser" value="test-service-1 (test-ca-1)" />
      <!-- Signature key attachment method.  We want to put the token
           directly in the header and not use a reference. -->
      <entry key="signatureKeyIdentifier" value="DirectReference" />
      <!-- Defines the property name that contains a Properties object with the desired
           settings in it.  Better than loading a static file from the classpath when using
           Spring. -->
      <entry key="SignaturePropRefId" value="signatureProperties" />
      <!-- The entry that actually contains the Properties object for
           the signature crypto configuration.  See SignaturePropRefId. -->
      <entry key="signatureProperties" value-ref="signatureProperties" />
      <!-- The parts of the response to sign. -->
      <entry key="signatureParts" value="{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body;{Element}{http://www.w3.org/2005/08/addressing}Action;{Element}{http://www.w3.org/2005/08/addressing}MessageID..." />

      <!-- The reference to the callback handler for retrieving passwords
           for private keys in the signature and encryption crypto configurations. -->
      <entry key="passwordCallbackRef" value-ref="pwCallback" />
    </map>
  </constructor-arg>
</bean>

Line 31 of the preceding XML configures the elements to be signed by WSS4J when it creates the message signature.  If WSS4J cannot find one of the elements listed in the signatureParts configuration entry, it throws an exception.  On the server side, if this exception is throw while handling another fault, say a fault triggered by an inbound security problem, CXF simply gives up and returns an empty response message.  This message is really and truly empty, no SOAP Body, no SOAP Envelope.  Depending on what went wrong to cause the original fault, the current message exchange pattern in use, and the validity of the inbound WS-A headers, CXF can provide some or all of the WS-A headers in a response.  When CXF only provides some of the headers in the response, this static configuration breaks down.

The Solution

There are two solutions to this problem in CXF: 1) configure security using WS-SP and 2) dynamically configure the WS-A headers to be signed.  While option 1 solves the problem, it also introduces the complexity of WS-SP.  For those not wishing to or unable to use WS-SP, solution 2 is described below.

The issue above may be resolved by dynamically determining the WS-A headers in the outbound message and adding them to the WSS4J signatureParts configuration option only when present in the message.  This feat is accomplished through the use of a custom CXF interceptor.  The interceptor works by inspecting the outbound message for all possible WS-A headers and adding the present headers to the existing signatureParts configuration property value.

The following code fragments illustrate how to configure this custom interceptor on the server side.  The client side configuration is nearly identical and can be seen in the complete working example in Subversion.

<jaxws:endpoint
  serviceName="service:CustomerServiceService"
  endpointName="service:CustomerServicePort"
  address="http://localhost:8080/services/CustomerService"
  wsdlLocation="classpath:/wsdl/CustomerService.wsdl"
  implementor="#defaultCustomerService">
  <jaxws:features>
    <!-- Configure the WS-Addressing feature. -->
    <addressing:addressing addressingRequired="true"
      allowDuplicates="false"/>
  </jaxws:features>
  <jaxws:inInterceptors>
    <ref bean="wss4jInInterceptor"/>
  </jaxws:inInterceptors>
  <jaxws:outInterceptors>
    <ref bean="wss4jOutInterceptor"/>
    <ref bean="dynamicWsaSignaturePartsInterceptor"/>
  </jaxws:outInterceptors>
  <jaxws:outFaultInterceptors>
    <ref bean="wss4jOutInterceptor"/>
    <ref bean="dynamicWsaSignaturePartsInterceptor"/>
  </jaxws:outFaultInterceptors>
  <jaxws:properties>
    <!-- The parts of the response to sign.  Include: Body, token,
         timestamp at a minimum. -->
    <entry key="signatureParts" value="{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body; Token; {Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp" />
  </jaxws:properties>
</jaxws:endpoint>

<bean id="dynamicWsaSignaturePartsInterceptor"
      class="valeri.blog.examples.cxf_wsa_sig.DynamicWsaSignaturePartsInterceptor"/>

<!-- Configure the outbound WSS4J interceptor. -->
<bean id="wss4jOutInterceptor">
  <constructor-arg>
    <!-- The entry keys in this map are defined in
         org.apache.ws.security.handler.WSHandlerConstants
         but are referenced as String literals here for brevity over
         the use of the util:constant element. -->
    <map>
      <entry key="action" value="Timestamp Signature" />
      <!-- This is the fallback user for sig/enc if the sig/enc specific
           properties are not set.  WSS4JOutInterceptor looks for it
           and fails if it is not set. -->
      <entry key="user" value="test-service-1 (test-ca-1)" />

      <!-- Timestamp TTL in seconds. -->
      <entry key="timeToLive" value="60" /><br />
      <!-- The certificate alias in the signature crypto config to sign
           the message with.  The password is retrieved from the callback handler. -->
      <entry key="signatureUser" value="test-service-1 (test-ca-1)" />
      <!-- Signature key attachment method.  We want to put the token
           directly in the header and not use a reference. -->
      <entry key="signatureKeyIdentifier" value="DirectReference" />
      <!-- Defines the property name that contains a Properties object with the desired
           settings in it.  Better than loading a static file from the classpath when using
           Spring. -->
      <entry key="SignaturePropRefId" value="signatureProperties" />
      <!-- The entry that actually contains the Properties object for
           the signature crypto configuration.  See SignaturePropRefId. -->
      <entry key="signatureProperties" value-ref="signatureProperties" /><br />
      <!-- The reference to the callback handler for retrieving passwords
           for private keys in the signature and encryption crypto configurations. -->
      <entry key="passwordCallbackRef" value-ref="pwCallback" />
    </map>
  </constructor-arg>
</bean>

Lines 17 and 21 add the new custom interceptor to the out and outFault interceptor chains of the server.  This addition ensures that both regular and fault responses from the server are equally secure.  These lines reference the DynamicWsaSignaturePartsInterceptor instance defined on line 30.

The next major difference is in the relocation of the signatureParts configuration option from the properties passed to WSS4JOutInterceptor to the properties defined on the service itself.  This configuration option now appears on line 26.  Note that the relocated property value also contains no configuration relating to any WS-A header elements.  This configuration property is relocated to optimize the performance of WSS4J.  When this property is left in its original position, the DynamicWsaSignaturePartsInterceptor is forced to manipulate the service interceptor chain in a way that prevents the caching of cryptographic configuration information.  By moving the configuration location, this caching can still occur.  The DynamicWsaSignaturePartsInterceptor can handle the configuration in either location but produces a warning in the logs when the configuration is not moved to the service definition.

Trying It Out

You will need a Subversion client, Maven 2.2.1, Java 1.5/1.6, and access to the Internet to retrieve the needed dependencies from the Maven repositories in order to build the sample code and the DynamicWsaSignaturePartsInterceptor interceptor.  The following instructions will guide you through retrieving the source code, building the code, and running the example.

1. Using a Subversion client, checkout a copy of the code from  https://davidvaleri.googlecode.com/svn/projects/examples/cxf-wsa-sig/tags/cxf-wsa-sig-1.0 to a local working directory.
2. Execute mvn install in the local working directory.  The build output will display similar to the following

   [INFO] BUILD SUCCESSFUL
   [INFO] -------------------------------------------------------------
   [INFO] Total time: 8 seconds
   [INFO] Finished at: Tue Sep 14 21:38:41 EDT 2010
   [INFO] Final Memory: 34M/254M
   [INFO] -------------------------------------------------------------

3. Execute mvn -P server in the working directory.  The example server will start and listen for incoming message.
4. Using another console window, execute mvn -P client in the working directory.  The example client will start and send messages to the server.  The server will log the messages to the console window for review.

If you review the captured messages to and from the server, you can observe the WS-Security Signature over all WS-Addressing headers in the message.  In the example fragment below, each WS-Addressing header, on lines 23-28, contains a wsu:Id element containing an ID that is referenced from the embedded message signature on lines 6, 9, 12, and 15.

<soap:Header>
    <wsse:Security xmlns:wsse="..." soap:mustUnderstand="1">
    ...
    <ds:Signature xmlns:ds="..." Id="Signature-39">
      <ds:SignedInfo>
        <ds:Reference URI="#id-41">
          ...
        </ds:Reference>
        <ds:Reference URI="#id-42">
          ...
        </ds:Reference>
        <ds:Reference URI="#id-43">
          ...
        </ds:Reference>
        <ds:Reference URI="#id-44">
          ...
        </ds:Reference>
      </ds:SignedInfo>
      ...
    </ds:Signature>
    ...
  </wsse:Security>
  <Action xmlns="..." xmlns:wsu="..." wsu:Id="id-41">http://customerservice.example.com/CustomerService/getCustomersByName</Action>
  <MessageID xmlns="..." xmlns:wsu="..." wsu:Id="id-44">urn:uuid:a2d9d794-60bc-48f8-b549-d7c4fb7ca083</MessageID>
  <To xmlns="..." xmlns:wsu="..." wsu:Id="id-42">http://localhost:8080/services/CustomerService</To>
  <ReplyTo xmlns="..." xmlns:wsu="..." wsu:Id="id-43">
    <Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
  </ReplyTo>
</soap:Header>

In this situation, you can either create the bundle from the JAR and distribute this bundle to your end users or you can couple PAX URL, Karaf Features, and Maven together to provide a small and easy to distribute installation descriptor.  In my case, I need a small and self-contained Zip package for distribution.  Creating bundles from the needed third-party JARs and distributing them in the Zip package would unnecessarily bloat the distribution package.  This blog post discusses how to combine the tools mentioned above to script the creation of OSGi bundles during installation of a Karaf Feature.

The Karaf Feature Descriptor

The code fragment below illustrates a simple feature descriptor that installs a user created bundle as well as an existing OSGi bundle from a Maven repository.

<features>
  <feature name="myFeature" version="1.0">
    <bundle>mvn:valeri.blog.examples/karaf-wrap/1.0</bundle>
    <bundle>mvn:commons-codec/commons-codec/1.4</bundle>
  </feature>
</features>

The URLs in each bundle element are PAX URL Maven Protocol URLs.  These URLs trigger the provisioning of the Maven artifact into the OSGi framework.

The following code fragment illustrates a feature descriptor that leverages the Wrap Protocol from PAX URL to provision a non-OSGi-ready artifact.

<features>
  <feature name="myFeature" version="1.0">
    <bundle>mvn:valeri.blog.examples/karaf-wrap/1.0</bundle>
    <bundle>mvn:commons-codec/commons-codec/1.4</bundle>
    <bundle>wrap:mvn:commons-beanutils/commons-beanutils-core/1.8.3</bundle>
  </feature>
</features>

All is well and simple so far, but what if you need to customize the wrapping by providing specific configuration options.  No problem, the PAX wrap capability uses the bnd tool under the covers and the bnd tool allows you to customize the generated bundle.  For complex configuration options, the bnd tool uses .bnd files.  Luckily,  PAX URL allows you to specify the location of such a file in the Wrap URL.  For example, the Wrap URL for Commons BeanUtils Core with a custom .bnd file would be formatted as follows.

wrap:mvn:commons-beanutils/commons-beanutils-core/1.8.3,file://~/myBnd.bnd

The above URL is great, if you know where the .bnd file will be located on the file system.  In my case, I am distributing a Zip file containing binary artifacts and Maven metadata.  There is no way to know where this file will be unzipped to on a user’s file system.  Fortunately, the location for the .bnd file can also be a Maven URL.  The following Wrap URL specifies the Maven artifact to convert to an OSGi bundle as well as the Maven artifact that describes the configuration for the bnd tool.

wrap:mvn:commons-beanutils/commons-beanutils-core/1.8.3,mvn:valeri.blog.examples/karaf-wrap/1.0/bnd/commons-beanutils-core-1.8.3

While the above URL looks complex, it simply states that the .bnd file is a Maven artifact with the following properties:

• GroupId: valeri.blog.examples
• ArtifactId: karaf-wrap
• Version: 1.0
• Type: bnd
• Classifier: commons-beanutils-core-1.8.3

By using a URL like the one above, you can avoid needing to have advanced knowledge of the location of the .bnd file and you can completely automate the conversion of the non-OSGi-ready artifact without needing to distribute the artifact yourself.  The next section will describe how to configure Maven to create and deploy the needed Karaf Feature descriptor and .bnd file.

Configuring Maven to Deploy Karaf Feature Descriptors and .bnd Files

The easiest way to attach these artifacts to your Maven build is to use the Build Helper Plug-in.  This Maven plug-in allows you to work with the Maven build process as well as to attach arbitrary artifacts to the Maven build.  The following POM fragment adds the feature descriptor and the .bnd file to the Maven build process using the Build Helper Plug-in’s attach-artifact goal.

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>build-helper-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>attach-artifacts</id>
      <phase>package</phase>
      <goals>
        <goal>attach-artifact</goal>
      </goals>
      <configuration>
        <artifacts>
          <artifact>
            <file>target/features/features.xml</file>
            <type>xml</type>
            <classifier>features</classifier>
          </artifact>
          <artifact>
            <file>target/bnd/commons-beanutils-core-1.8.3.bnd</file>
            <type>bnd</type>
            <classifier>commons-beanutils-core-1.8.3</classifier>
          </artifact>
        </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>

In the above code fragment, the attached artifacts are retrieved from the target folder of the build.  While it is possible to attach static artifacts that live in the source tree, it is often convenient to use filtering of tokens in these files to avoid needing to update version numbers between releases.  In this example, the .bnd files and feature descriptor are copied and filtered into the target/bnd and target/features folders, respectively.  By default, Maven copies resources into the target/classes folder.  In order to keep these files out of the bundle and off the classpath when creating the feature descriptor as part of the bundle module, two additional executions of the Maven Resources Plug-in must be configured.  The following POM fragment illustrates the configuration of these executions.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-resources-plugin</artifactId>
  <executions>
    <execution>
      <id>copy-features</id>
      <phase>generate-resources</phase>
      <goals>
        <goal>copy-resources</goal>
      </goals>
      <configuration>
        <outputDirectory>target/features</outputDirectory>
        <resources>
          <resource>
            <directory>src/main/features</directory>
            <filtering>true</filtering>
          </resource>
        </resources>
      </configuration>
    </execution>
    <execution>
      <id>copy-bnd</id>
      <phase>generate-resources</phase>
      <goals>
        <goal>copy-resources</goal>
      </goals>
      <configuration>
        <outputDirectory>target/bnd</outputDirectory>
        <resources>
          <resource>
            <directory>src/main/bnd</directory>
            <filtering>true</filtering>
          </resource>
        </resources>
      </configuration>
    </execution>
  </executions>
</plugin>

The above configuration, coupled with other configuration in the project POM will deploy the needed artifacts to the Maven repository.  You can look at the deployed artifacts that were created by the above configuration by browsing to https://davidvaleri.googlecode.com/svn/repo/valeri/blog/examples/karaf-wrap/1.0/.

To see the complete example configuration and source files, you can browse the example tag in SVN at https://davidvaleri.googlecode.com/svn/projects/examples/karaf-wrap/tags/karaf-wrap-1.0.  You can also use this URL to checkout the example code and build it yourself.  To build from the source, you will need Maven 2.2.1, Java 1.5/1.6, and access to the Internet to retrieve the needed dependencies from the Maven repositories.

Putting it All Together and Deploying The Feature

Once the artifacts are deployed to a Maven repository, either your local repository or a repository on the network, you can provision them into OSGi using Karaf Features.  The easiest way to work with Karaf Features and the other OSGi tools used above is to get an OSGi container that already comes with the needed tools installed.  Apache ServiceMix provides these tools out of the box.  These instructions will use the supported FUSE distribution available at http://fusesource.com.  If you don’t use ServiceMix, you will need to install and configure Karaf Features, PAX URL, and Spring DM in your OSGi container to execute this example.  Use this link to download the Zip installer.  Simply extract the Zip file and execute the servicemix script in the bin directory.  The extracted location of the Zip file will be referred to as $SERVICEMIX_HOME in these instructions.  After you execute the script, you will be presented with a shell environment used in the following instructions.

1. Add the example Maven repository to the PAX URL configuration by opening $SERVICEMIX_HOME/etc/org.ops4j.pax.url.mvn.cfg in a text editor.
   1. Edit the org.ops4j.pax.url.mvn.repositories property by appending , http://davidvaleri.googlecode.com/svn/repo/ to the last line of the property value.
   2. Save your changes to this file.
2. In the shell environment, type features:addUrl mvn:valeri.blog.examples/karaf-wrap/1.0/xml/features and press enter to add the feature to the list of known features.  Karaf Features is now aware of the feature.
3. In the shell environment, type features:list | grep myFeature and press enter.  The information for the newly added feature will display.
4. In the shell environment, type features:install myFeature and press enter.
5. In the shell environment, type osgi:list and press enter.  A list of installed OSGi bundles displays.  The last three entries in the list are the bundles installed by the new feature. Your output should look like the text below.

   [ 207] [Active     ] [            ] [Started] [   60] David Valeri's...
   [ 208] [Active     ] [            ] [       ] [   60] Commons Codec (1.4)
   [ 209] [Active     ] [            ] [       ] [   60] Commons BeanUtils...

6. Open $SERVICEMIX_HOME/data/log/servicemix.log and observe the log output generated by the installed feature. The log should contain output that resembles the following.

   --------------------------------------------
   23:08:14,937 | INFO  | raf_wrap.Example | Example | og.examples.karaf_...
   --------------------------------------------
   Protocol: http
   Host: davidvaleri.wordpress.com
   Path:
   --------------------------------------------

Conclusion

While this is a fairly trivial example using only a single JAR, this approach can help you to migrate legacy JARs to OSGi without needing to maintain binaries for each converted JAR or build each converted JAR from source.  Avoiding the need to pass these converted JARs out to my clients in the Zip means that the Zip need only contain my application binaries which are not available in a public repository.

<bundle>mvn:valeri.example/karaf-wrap/1.0</bundle>