NHIN DIRECT
.NET HISP Reference Implementation Overview (versions 1.*)
Project Overview
The .NET HISP Reference Implementation is intended to serve both as an “out of the box” system for
providing NHIN Direct messaging services, and as an extensible set of components that can be
integrated into an existing environment.
The loosely-coupled components that make up the reference implementation include:








The Security Agent that performs S/MIME encoding and decoding, and enforces the NHIN Direct
Security & Trust requirements.
An SMTP gateway that inserts the agent code in front of any standard SMTP email server,
handles error conditions, etc... The gateway can also drop/pickup messages from file system
folders as a loosely-coupled integration point for non-SMTP systems.
A configuration system that holds account, preference and certificate information in a
database, and exposes web services for retrieving and manipulating configurations.
A web-based configuration UI that sits on top of the default configuration system.
A DNS responder service for MX and CERT record distribution.
An audit logging system that accepts audit events for storage.
Miscellaneous utility code such as a DNS resolver, MIME parsing tools used by other
components, and policy enablement engine.
An XDD gateway that enables communication between IHE/NHIN nodes and the NHIN Direct
SMTP backbone.
The following diagram provides an overview of the full implementation; subsequent sections will detail
the functionality, interfaces and dependencies of each component.
License and Dependencies
The reference code is licensed under the BSD license per the terms of the NHIN Direct project.
The code is built to install on Windows Server 2008 and requires use of the built-in SMTP service that
comes with the OS. The built-in configuration database requires the use of the free SQL Server Express
2008, although we do not plan to use any SQL Server-specific database functionality, so other databases
should be usable. No other licensed code is required to run the system.
The code will build against the .NET 3.5 libraries using MSBuild. Mono is not an explicit target of the
reference implementation, although when reasonable we will attempt to use functionality that will build
and run in that environment.
Component Overviews
Each of these components will require their own specifications and documentation. Here we are
providing broad outlines that in particular discuss how the components will fit together from a systems
perspective.
Security Agent
The security agent is a standalone assembly that signs and encrypts outgoing messages, and decrypts
and verifies incoming ones. It does all of its processing synchronously and maintains no state. The toplevel functions provided by the agent simply correspond to these two actions:


ProcessIncomingMessage
ProcessOutgoingMessage
The agent depends on the code embedding the agent to provide implementations of the following
interfaces (defaults are provided as noted):
1. Retrieve configuration information (settings and private keys) for a local address. Also retrieve
instance-level configuration settings. The default implementation calls the reference
Configuration Service.
2. Retrieve public certificates for an address. The default implementation uses the reference DNS
resolver to fetch these certificates as CERT resources.
3. Resolve a certificate chain by walking from a starting certificate up to its root. The default
implementation uses the reference DNS resolver to fetch intermediate certificates.
4. Handle error and exception cases during processing. There is no default implementation of this
interface as handling rules are unique to each different site where the agent may be embedded.
Note that the security agent does NOT perform audit or other logging; it is the responsibility of
the code embedding the agent to do this.
SMTP Gateway
The SMTP Gateway is implemented as an “OnSubmission” transport event handler wired into the
Windows SMTP Service. The business logic for this handler exists in a standalone assembly called
through interop by a thin C++ COM shim that actually is registered with the service and handles
asynchronous behavior and other plumbing.
In the default configuration, the SMTP gateway is configured to sit directly between a “real” SMTP
server and the Internet. The gateway server accepts all incoming mail for local domains, passes it
through the “ProcessingIncomingMessage” method of the security agent, and relays the resulting
message to the real server. The real server accepts outgoing mail from local clients and relays it to the
gateway, which passes it through the “ProcessOutgoingMessage” method of the security agent and then
relays it out to the Internet for delivery.
Addresses may also be configured as “file type” addresses – in which case messages will be dropped to a
file system folder rather than being forward through the SMTP pipeline. The gateway will also monitor a
“pickup” file system folder through which cleartext messages can be submitted for sending.
The gateway server uses the MAIL FROM information to determine if a message is sourced remotely or
locally for purposes of appropriate inbound vs. outbound processing.
The gateway generates error and MDN (message disposition notification) and DSN (delivery status
notification) notifications based on responses from the agent. The contents and features of these can be
managed through configuration.
The SMTP Gateway depends on the following interfaces:
1. Security Agent processing. The default implementation uses the reference security agent
configured with all default interfaces. The Gateway implements error and exception handling
needs of the agent.
2. Retrieve configuration settings. The default implementation uses the reference Configuration
Service.
3. Audit logging. The default implementation uses the reference Audit Log service.
Configuration Service
The configuration service is primarily a simple database with a WCF service brokering access. The web
service is read/write and implements a security model that permits both system administrators and
specific account owners to manage their configurations.
The following schema is for directional reference purposes only; the real version will live in a specific
design document for the configuration service:
Many of the tables reference an “Owner” field --- this is a FK to either the Domains or Addresses table …
the idea being that you can have settings, certificates, etc. at the address or domain level. In general,
there is an inheritance from Addresses to Domains for these tables. However, the behavior is subtly
different and important:
1. The Certificates and Anchors tables behave as follows. When certs are requested for an Address,
if there are any associated with the address, they are returned and processing stops. If there are
none, the associated domain is checked and any certificates there are returned. This is very
important --- because it supports the flexible relationship between org/endpoint certs
required by the Direct specification.
The configuration web service will use simple WCF calls, secured using machine accounts --- access to
the service itself is not user authenticated --- so it should be called by trusted users. The configuration UI
will validate usernames and passwords using a web service created for that purpose.
In addition to utility code for managing certificates, the configuration service relies on the following
interfaces:
1. Audit logging. The default implementation uses the reference Audit Log service.
Configuration UI
The configuration UI is a simple ASP.NET MVC web site used by administrators (both system
administrators and domain/account/address administrators) to manually configure the reference
implementation. The site manages logins and then calls configuration service methods as appropriate.
The configuration UI relies on the following interfaces. Note the UI does NOT rely on audit logging; it
depends on the underlying service to perform auditing as required.
1. Retrieve and set configuration settings. The default implementation relies on the reference
configuration service.
DNS Responder and Web Service
The reference implementation will include a simple DNS responder and DNS web service that answers
MX and CERT requests using information from the configuration store. Not the configuration service
exposes administration to the DNS data in the configuration store while DNS web service is a query only
service.
The DNS responder relies on the following interfaces.
1. Retrieve configuration settings.
2. The default implementation relies on the reference DNS web service.
Monitor Service
Monitor service is an optional service. It contains the following monitoring tasks.
1. Mdn monitor is a collection of jobs. The jobs monitor MDN confirmations from Direct partners.
If a MDN is not retrieve in a specific time period a DSN will be sent to the internal sending client.
Audit Log
The reference audit log implementation will simply send all audit events to the Windows Event Log.
Utility Code
Parsing of Mime, MDN, and DSN messages used by other libraries. Resolvers in the form of DNS and
LDAP. Policy engine used to validate certificates against a policy.
Tools
Four utility tools exist today.
1. ConfigConsole: All administration of the configuration store can be performed from this
command line tool. All commands can be batched up in text files or scripted.
2. AgentConsole: A command line client DNS tool. Use this to test DNS resolution against your
DNS Resolver.
3. AdminConsole: A command line user administration tool. Create credentials for the web based
Admin UI.
4. Trust.Bundler: A trust bundle creator exposed as a PowerShell Cmdlet.
XDD Gateway (.net has only partially implemented this spec)
The reference implementation will also include an XDD gateway service for translating messages
between the SMTP backbone and an IHE/NHIN node. The service will hook into the SMTP gateway using
the loosely-coupled file system folder interface.
At the highest level, the XDD gateway will work as follows:
1. Addresses will be configurable as “file addresses”, meaning that messages sent to that address
should be saved to a file system folder rather than forwarded to a target SMTP server. It will also
be possible to configure this on a system-wide basis for all addresses.
2. SMTP-to-XDD. When a message is saved to the drop folder after agent processing, it will be
picked up by the XDD gateway, converted into an XDD message and sent to the appropriate
endpoint. If the message cannot be “stepped up”, a bounce notification will be sent.
3. XDD-to-SMTP. The reference implementation will include a web service running to listen for
XDD messages coming from locally-configured senders. These messages will be turned into
XDM-packaged SMTP messages and submitted to the SMTP gateway through the file system
pickup folder.
Document History
Joe Shook
Surescripts
3/31/2013
Sean Nolan
Microsoft
8/17/2010
Sean Nolan
Microsoft
7/24/2010
Update diagrams to
include monitor service,
trust bundle tool, trust
bundle client featurs
and db schema
changes.
Edited to update
diagram and misc. for
current understanding
and plans
Initial Draft