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 and MIME parsing tools used by other components.
· 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 top-level 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.
- 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
Four utility tools exist today.
- 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.
- AgentConsole: A command line client DNS tool. Use this to test DNS resolution against your DNS Resolver.
- AdminConsole: A command line user administration tool. Create credentials for the web based Admin UI.
- Trust.Bundler: A trust bundle creator exposed as a PowerShell Cmdlet.
XDD Gateway (.net has only partially implanted 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/30/2013 / Update diagrams to include monitor service, trust bundle tool, trust bundle client featurs and db schema changes.Sean Nolan / Microsoft / 8/17/2010 / Edited to update diagram and misc. for current understanding and plans
Sean Nolan / Microsoft / 7/24/2010 / Initial Draft