Previous: Up: Deploymenet GuideEnd of book

HISP Only Deployment (no source)

This section outlines step by step instructions on installing and deploying a Bare Metal instance of the Java reference implementation. The instructions contains steps for a select list of software platforms such as Windows and Ubuntu linux.


General Tools and Runtimes

The reference implementation requires some tools to be available on the platform to install and run the Bare Metal components.


An unzip tool is required to unpack the stock assembly. Recommended tools and installation locations are listed below:


Any one of the following will work for Windows:


Install unzip using the following command:

 sudo apt-get install unzip


Unzip tools should already be installed, but if not execute the following commands with root or sudo privileges:

 yum install unzip
 yum install gzip
 yum install tar


The Ant tool is used for setting the domain name in the Apache James server.


Download Apache Ant from the following location and follow in the install instructions under Documentation/Manual located on the upper left side of the site below


Install ant using the following command:

 sudo apt-get install ant



Java 6 SE

The Java 6 SE platform provides the runtime environment that all of the Bare Metal components will run in.


Download and install the Java 6 JRE from Oracle's download web site. After installing the JRE, set the JAVAHOME environment variable by following the instructions below:

  • Right click on "My Computer" (may be in different locations depending on the Windows version) and select Properties
  • If running later versions of Windows, you may be presented "ControlSystem" panel. If so, click Advanced system settings on the left side of the window.
  • In the System Properties Dialog, click the Advanced tab and then click Environment Variables.
  • Under System Variables click New.
  • Use the following setting:
    • Variable Name: JAVAHOME
    • Variable Value: C:Program Filesjavajre6
  • Click OK on all screens.

Ubuntu 10.10 - 11.10

Install Sun Java 6 JDK. By default it is not included in the shipped repository, and needs to be added manually. After installing, you need to update java-alternatives to use the newly installed Java version instead of shipped version.

Note: For Ubuntu 10.10 Maverick, the add-apt-repository command may not be not available. Instead, uncomment or add the canonical repository " lucid partner" in the /etc/apt/sources.list and follow the remainder of the steps.

 sudo add-apt-repository "deb lucid partner"
 sudo apt-get update
 sudo apt-get install sun-java6-jdk
 sudo update-java-alternatives -s java-6-sun
 export JAVA_HOME=/usr/lib/jvm/java-6-sun
 echo "export JAVA_HOME=$JAVA_HOME" >> ~/.bashrc

Note: It is okay to ignore the "no alternative" error messages displayed after running the update-java-alternatives command.

Ubuntu 12.04

The Sun JDK 6 has been moved to a Personal Package Archive (PPA) for 12.04. You will need to add Flexiondotorg repository to install the Sun JDK.

Similar to previous versions of Ubuntu, you need to update java-alternatives to use the newly installed Java version instead of shipped version.

Note The add-apt-repository command may not be available. Adding the python-software-properties package should resolve this issue. It is also okay to ignore the "no alternative" error messages displayed after running the update-java-alternatives command.

 sudo apt-get install python-software-properties
 sudo add-apt-repository ppa:flexiondotorg/java 
 sudo apt-get update
 sudo apt-get install sun-java6-jdk
 sudo update-java-alternatives -s java-6-sun
 export JAVA_HOME=/usr/lib/jvm/java-6-sun
 echo "export JAVA_HOME=$JAVA_HOME" >> ~/.bashrc


Obtain/downlaod the JDK 6 Update 29 package using the following command for the appropriate processor architecture:

x86 (32 bit)


x64 (64 bit)


After downloading, execute the following commands to install the JDK for the appropriate processor architecture:

x86 (32 bit)

 chmod 755 jdk-6u29-linux-i586-rpm.bin
 sudo ./jdk-6u29-linux-i586-rpm.bin

x64 (64 bit)

 chmod 755 jdk-6u29-linux-x64-rpm.bin
 sudo ./jdk-6u29-linux-x64-rpm.bin

After installing, you need to update java alternatives to use the newly installed Java version instead of shipped version. Start by creating alternatives for the new java commands installed above. Execute the following commands to set the Sun JDK:

 sudo alternatives --install /usr/bin/java java /usr/java/jdk1.6.0_22/bin/java 100
 sudo alternatives --install /usr/bin/jar jar /usr/java/jdk1.6.0_22/bin/jar 100
 sudo alternatives --install /usr/bin/javac javac /usr/java/jdk1.6.0_22/bin/javac 100
 sudo alternatives --config java
 sudo alternatives --config jar
 sudo alternatives --config javac 

Finally set the JAVAHOME environment variable for the new JDK using the following commands:

  export JAVA_HOME=/usr/java/jdk1.6.0_22
  echo "export JAVA_HOME=$JAVA_HOME" >> ~/.bashrc

Java Cryptographic Extensions

The Sun JRE/JDK requires the JCE policy jars to be updated to allow for unlimited strength encryption. The policy files must be downloaded separately and copied in the JRE library.

For all platforms, download the jce policy file using a web browser. For Unix/Linux systems, it may be necessary to manually copy or FTP the file from a system with a UI to the Unix/Linux node.


Unzip the downloaded file and copy the jar files from the jce directory to the JAVAHOME/jre/lib/security folder (Example: C:Program Filesjavajre6libsecurity). Overwrite the existing files.

All Linux/Unix

From the directory where you downloaded and placed the jce zip file, run the following commands:

 sudo cp jce/local_policy.jar $JAVA_HOME/jre/lib/security
 sudo cp jce/US_export_policy.jar $JAVA_HOME/jre/lib/security

Obtain Reference Implementation Stock Assembly

The stock assembly contains all of the pre-assembled and configured components of the Bare Metal deployment. Download the latest version of the stock assembly from the maven central repository or the Sonatype repository.

Note: The maven central repository may black list some IP ranges such as virutal machines running in the Amazon EC2 cloud. Use the Sonatype repository if you are blocked from the maven central repository.

The assembly contains a root directly named direct and has the following folders under the root.


From a browser, download the desired version of the assembly from one the repositories above.

Example: Download version 1.4 - direct-project-stock-1.4.tar.gz. After downloading, unzip the contents to appropriate installation location.

All Linux/Unix

Obtain the URL for appropriate version of the assembly and download it the /opt directory by running wget command from the /opt directory. For example, to download version direct-project-stock-1.4.tar.gz from maven central, use the following commands:

 cd /opt

If you are denied access to the location above, try the Sonatype repostitory using the following command.

 cd /opt

Extract the contents of the assembly and set the DIRECT HOME logical using the following command. Note the name of the tar.gz file if you downloaded a different version:

 tar xvfz direct-project-stock-1.4.tar.gz
 export DIRECT_HOME=`pwd`/direct
 echo "export DIRECT_HOME=$DIRECT_HOME" >> ~/.bashrc

Launch Tomcat and Configuration Services

Before running the James mail servier, the configuration services must be running and some minimum configuration completed. All of these services run inside the Tomcat web server.

To start the tomcat server, run the following command from the DIRECT HOME/apache-tomcat-7.0.27/bin directory.



All Unix/Linux


Note: It may take a few minutes for the web server to finish loading as it must initially deploy all of the services when run for the first time.

To validate that Tomcat and the configuration services loaded successfully, launch a browser window against the server node with the following URL:


You should be presented with the configuration ui login screen

Domain Name and Certificate Generation

The first step in running your mail server is configuring the domain and a loading a trust anchor and certificate into the configuration ui.

First determine your HISPs domain name. Depending on the type of certificate resolution services you wish to host, your domain nameing convention may slightly differ. Regardless of the certificate hosting model, you will need to have to have registered domain. For this document, we will assume you have a domain registered called

Note: Refer to the Direct Project DNS Configuration Guide as a starting point for determining your DNS naming convention.

Now that we have our registered domain, we will host our HISP Direct messaging under the domain

The next step is create a root certificate (anchor) for our domain and an X509 certificate for encrypting/decrypting and signing message. There are many different options for getting these certiicates such as using openssl or obtaining a certificate from a comercial third party such as Entrust or VeriSign. However the Direct Project reference implementation assembly ships a tool called certGen for generating root CAs and certificates for the purpose of pilots and interop testing.

Full documentation for the certGen tool can be found here. The documentation in the certGen link runs the certGen tool from the reference implemntation source tree. In the Bare Metal assembly, the certGen tool is found under the /direct/tools directory that was extracted from the tar.gz file.

Run the certGen tool from tools directory using the following command:



All Unix/Linux


Now create a CA for your domain. In the certGen tool, enter a common name (CN:) for your new CA. For our domain, we might use something like Direct.Example.Com Root CA. Fill the other fields as needed. It is recommended you set the expiration to 1 year, the key strenth to at least 2048 bytes, and provide a password for your CA's private key.

After creating the CA, create a leaf cert and using your domain name as the CN: field and fill in all other fields as needed. It is recommended you set the expiration to 1 year, the key strength to at least 1024 bytes, and provide a password for your private key. Also make sure the Add Email To Al Subject Names is checked. After creating your CA and certificate, you should have to following similarly named files in your /tools directory (assuming the domain and no email address entered in the CA dialog. If an email address is entered, then the CA files will have the eamil address in the file name instead of the CN field).

Import Anchors and Certificates

Before the James mail server can be run, you must create you domain in the configuration ui tool and import anchors and certificates. Follow the steps below to create your domain and import your trust anchor and certificate. A full description of the config ui and operations can be found here.

  1. Log into http://<server>:8081/config-ui with username: admin and password: adm1nD1r3ct
    1. Click Create New Domain.
    2. Enter the Domain Name and Postmaster E-Mail Address for the domain this HISP will be handling. Typical postmaster address is postmaster@<domain name>.
    3. Choose ENABLED as the status.
  2. Click the Anchors tab.
    1. Click choose file, browse to the location of your trust anchor, and select it.
    2. Check Incoming and Outgoing
    3. Choose ENABLED as the status.
    4. Click add anchor
    5. Click cancel to return to the home screen
  3. Click Certificate at the top of the screen
    1. Click choose file, browse to the location of you org certificate PKCS12 file, and select it
    2. Choose ENABLED as the status.
    3. Click Add Crtificate
    4. Click Cancel to return to the home screen

Note: You do not have to enter any additional agent setting in version 1.2 and higher of the Bare Metal assembly. The agent automatically defaults to standard settings for optimal interoperability.

Before your HISP can communicate with other HISP, you must import anchors from other HISPs to estabilish trusted communication. You must also provide your trust anchor to the HISP(s) you are communicating with. There are a few options of HISPs that exist for interop testing that can be easily accessed. Anchors of these HISP can be found and downloaded from the Direct Project google code source page.

Configure and Run James Mail Server

First, configure james with your domain name.


Manually edit the file config.xml under DIRECT HOME/james-2.3.2/apps/james/SAR-INF and change the following settings.

All Unix/Linux

Run the following commands:

 cd $DIRECT_HOME/james-2.3.2
 sh bin/ <your domain name>

Now start the Apache James mail server with security and trust agent with the following commands:


From the DIRECT HOME/james-2.3.2/bin directory run:


All Unix/Linux

 cd $DIRECT_HOME/james-2.3.2
 sudo -E sh bin/ > james.log 2>&1 &

Now add your first user by running the following commands:

Note For Windows Users: You will need to open a separate command window from the previous step. Later versions of Windows do not come with the Telnet client installed. You have to manually install this using the server manager console.

 telnet localhost 4555
 > root
 > root
 > adduser username password
 > quit

Note: The username should not contain @domainname. This is required for James 3+, but should not be used for James 2.3.2.

DNS Records

Now that your HISP is running, you need to make it available to the public internet. If you intend to make your HISP's certificate available via DNS CERT records, you will need to install and configure the Direct DNS Server. Instructions can be found in the DNS Servers users/deployment guide. This guide includes directions on integrating with GoDaddy.

If you are not using DNS to distribute your certificates, you may use your registrar's DNS configuration tooling to setup MX records for you HISP.

Distributing Certificates

The prefered distribution mechanism for distributing your HISP's org certificate is DNS CERT records. Instructions for setting up the Direct DNS server are found in the DNS server deploymenet guide.

Another alternative still in the formalization stage is LDAP. The default settings in the security and trust agent will attempt to use the Direct LDAP specication if SRV records can be found. The LDAP standards can be found on the S&I framework's Certificate Discovery for Direct Project workgroup page.

A fall back alternative is manually distributing your org certificate to the HISPs that you will communicate. This is an out of band process that will require you to determine how to get your certificate to the HISP. Likewise another HISP may need to manually give you their certificate(s) if they do not support DNS or LDAP discovery. To add another HISPs certificate (not anchor) to you HISP, import the certificate file into the Certificates section of the configuration ui tool.

Recommended Next Steps

Following are optional, but recommended, next steps to secure your environment.

Secure Configuration Service Port (8081)

To secure the configuration service, it is recommended to limit access to port 8081 to localhost and/or a local subnet.

Secure Configuration Service Password

To further protect the configuration service, or if port 8081 must remain public, it is recommended to change the default password.


Manuall edit the config-servlet.xml file under DIRECT HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF and change the following setting to your new password:

 <security:user name="admin" password="adm1nD1r3ct" authorities="ROLE_ADMIN"/>

Restart the tomcat server by running the following commands from the DIRECT HOME/apache-tomcat-7.0.27/bin directory.


All Unix/Linux

 cp $DIRECT_HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF/config-servlet.xml $DIRECT_HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF/config-servlet.xml.orig
 sed -i "s/adm1nD1r3ct/your_new_password/g" $DIRECT_HOME/apache-tomcat-7.0.27/webapps/config-ui/WEB-INF/config-servlet.xml
 sh bin/
 sh bin/

Previous: Up: Deploymenet GuideEnd of book