Summary
The Direct Project is an encrypted email package that can be setup and configured to allow doctors to send protected health information (PHI) from one system to another over the Internet. For those who work in the health software industry, this system is necessary in order to meet Meaningful Use Stage 2 (MU2) certification. In this post, I’m going to give a very broad stroke of how you can get started in setting up and troubleshooting this system.
The Direct Project Basics
The Direct Project is a collection of programs that are used to encrypt and decrypt email messages using X.509 public key encryption. This system requires a standard windows SMTP server as well as DNS, WCF and a host of other technologies to perform the task of encrypting an email message using the recipient’s public key, signing the message with the sender’s private key and sending the message to another direct messaging system. Of course, the reverse is also performed, by verifying the signature of the incoming message and decrypting the message before delivering to the email client.
Where to Get Started
The only location (as of this blog post) where you can get information is at the wiki page for the project. You can get to the wiki by this link: http://wiki.directproject.org/ .
If you attempt this project, the first thing you’ll notice is that the documentation is really bad. Most of the site is dedicated to the development of the project. It is organized as a giant clearing house of raw notes and descriptions. It takes a long time to dig around and find where to start and what to actually do. The next thing you’ll discover about this project is that there is nothing on the internet of value. Which I found to be shocking. The fact that the Internet is empty of information, tells me that other companies either struggled like I did, or they are using another company for their Direct Project system. Two companies that I’ve investigated are Kno2 and SureScripts. If you are on a budget or these systems do not fit your needs, then you’ll need to follow the instructions on the direct project wiki page and start from there.
To setup the system you can start with the bare-metal C# installation page, here: http://wiki.directproject.org/CSharp+Setup+Instructions. I’m assuming that you’re going to use the C# version of this system. The instructions are a bit disorganized. First, you’ll have to setup the basic SMTP Windows Server (2008 or 2012 instructions are provided). I would recommend sticking to Windows Server 2008R2 due to the fact that the web.config files and many other pieces of the system are already configured for this OS. If you choose a newer OS, then you’ll need to perform more work to make the system work.
Inside the bare-metal instructions are some links to other instructions for setting up the software and turning on the Windows features required to run the system. Don’t forget to watch the video for turning on the Windows Server features that you’ll need. I have set this system up several times and I always miss something.
If you want to know more about certificates and anchors, there is a link on the wiki to a blog post that starts here: How Encrypted Email Works. It’s a very well written 3-part post that explains public key encryption in the most basic terms. Other sites that explain X.509 encryption are absolutely eye-glazingly boring.
Where to Get the Direct Project Installer and Source Code
At one time the source code was hosted by code.google.com. Unfortunately, Google has discontinued that software and it appears that they turned it into a read-only website before the direct project organizers had a chance to install a forwarding message (or link). So after a bit of digging around I found the location of the current software. Ignore the forum posting at the bottom of the install binaries page where a link to “Direct-1.0.0.10-NET35.exe” is provided. This is old. To get the latest installer, you must go to the TeamCity server and download the installer. There is a tiny link in the wiki that references codebetter or you can click here to get it: http://teamcity.codebetter.com/viewLog.html?buildId=136221&tab=artifacts&buildTypeId=bt1231. Click on the “log in as guest” link to get in. At the top of the list is the latest version. Look for the latest version that is green. Under the “Artifacts” column there is a down-arrow next to the “View” link. Click that and you’ll see an installer that you can click on to down-load. Version 1.2.0.45 is the latest version as of this blog post.
If you’re looking for the source code that was used to build the latest version, it is currently hosted on GitHub: https://github.com/DirectProject/nhin-d.net35. I would strongly recommend downloading the source code for the version that you are installing. I have used the source code to insert additional logging in order to troubleshoot my installation. It’s unfortunate, but the logging that exists is not very helpful and the configuration settings are numerous and confusing (until you understand what the source code is doing).
Top Level Troubleshooting Tips
One of the largest holes in the whole project is the lack of troubleshooting help. If I were in charge of developing this system, I would have broken this into distinct pieces that flow from one direction to another. Each piece of the puzzle would have some sort of test setup. Logs, fake inputs, test programs. Whatever it takes to split this system down to something manageable. There is nothing more frustrating than a system that must be setup and configured entirely before being able to test one message. This system requires all the stars to be aligned before anything works. At this point, I’m going to list a few very top-level troubleshooting tips. These are the areas where I have found my problems.
The first step in troubleshooting is to setup the test system in the bare-metal setup. If you want to insert some test data into the database, there is a txt file with commands that are used by the configconsole.exe file. It’s called “setupdomains.txt”. You can open up a console and run “configconsole batch setupdomains.txt” to populate your database.
Once everything is setup, there is a small test you can perform by copying a test email file (.eml file) into the pickup folder. This will test the gateway software, which is responsible for intercepting the message and encrypting the contents. There is a test eml file in the samples directory.
You’ll need to make sure that your DNS server is setup to point to the SMTP server that you installed the software onto. I would recommend using the MxToolbox website to check this (http://mxtoolbox.com/SuperTool.aspx). In fact, MxToolbox is my favorite tool for testing DNS problems. You’ll need an MX record so that any emails sent to your domain are properly routed to the direct SMTP server. An “A” record must be setup to point to the proper IP address of the server. Finally, you’ll need to create a CERT record to contain your public cert for the domain address. Most DNS servers do not support CERT records, so beware. I use Dyn (http://dyn.com/dns/) to perform the DNS functions for the direct servers. It’s cheap and it supports CERT records. The interface is very easy to use.
Once you drop an email into the pickup folder, you can check the application logs to see if there were any errors when sending or receiving email. Go to your Administrative Tools -> Event Viewer. Expand the “Windows Logs” -> “Application” and you’ll see application events. The gateway software will log errors to this event log.
Wireshark is your friend. You can download wireshark for free and set it up to monitor port 25. Use “tcp.port eq 25 or icmp” as your wireshark filter. When you send a message, you should see some lines of data in wireshark showing the communication between your smtp server and the remote server. If you don’t get communication here, then you need to look at firewall settings for port 25 and also make sure your IP address is accessible from the outside world (maybe by using NAT).
You’ll also need the Direct Certification Discovery Tool (http://sitenv.org/direct-certificate-discovery-tool). The first test you must pass is the DNS test. Assuming you’re using a DNS server to host your public certificates, you should be able to select test H2 for a domain level address scheme. This test will give detailed messages to indicate where your trouble is. Your certificate must contain the url of the MX record where the CERT record is setup. If it doesn’t match, you’ll get an error indicating a mismatch.
The Direct Certificate Discovery tool will also allow you to test different certificate scenarios. You’ll need to use this test tool after you have installed your own certificates for your domain and create one or more test email accounts. I created an eml file for each of the 16 tests that they have setup. I keep these files on my direct server desktop so I can drop one in the pickup folder and check the results. Before you can run any tests, you’ll need to go to the discovery website and setup your email address that you would like to receive results. Below shows an example where the “From” address of the test eml file will contain “mydirectemail@mydirecturl.com” and the email address that will receive the results of the test will be “mynormalemail@myurl.com”:
If your direct server is working, you should get an email in your inbox with the test results. If there are any errors (such as failed encryption), then you’ll get a list of detailed errors. These error messages are somewhat cryptic at first, but they do point you in the right direction.
Insert extra logging in the source code, compile and copy the dlls up to the server. I downloaded the source code from GitHub, added my own application logging lines of code, recompiled and copied the resulting dlls up to the server to add extra test logging. This has pointed out configuration errors that I’ve made and led me to problems with my database setup. When you get really stuck, this is where you’ll need to go. For my testing, I have a gateway solution where I have pulled only the source I needed for the gateway to compile. The solution posted is in VS2012 and earlier, but I’m using VS2013 with no problems. You’ll need to do an “iisreset” before copying new dlls since iis will lock some of the dlls. If you change the gateway config file, you’ll also need to do an “iisreset” to cause the new parameters to be read by the gateway software.
I’ll be going into more details in future posts, so stay tuned.