REST Implementation

REST Implementation

version 1.3

Overview

This document suggests a mapping of RESTful APIs onto the associated NHIN Direct Abstract Model. The overarching theme of this mapping is the use of currently existing and widely understood Internet technologies/services/standards.

A REST Implementation Development Team is being organized to advance this proposal to a concrete instance. Please join that team if you have expertise, software development skills, and time to contribute.

A REST-based API typically manifests itself by specifying a set of methods constrained by the HTTP protocol (usually GET, POST, PUT, and DELETE) that can be applied to resources expressed as URIs. Return values are presented using the typical HTTP status code mechanism along with content distinguished by MIME type. A good REST introduction may be found here.

NHIN Direct Message

• Multipart MIME. A good overview of MIME may be found here including a listing of relevant IETF RFCs.

NHIN Direct Source Edge Protocol

• HTTP over TLS (HTTPS) with a corresponding REST API.

NHIN Direct Destination Edge Protocol

• HTTP over TLS (HTTPS) with a corresponding REST API.

NHIN Direct Address

• NHIN Direct Address (Health Domain Name and Health Endpoint Name) mapped appropriately to REST URIs. As noted in the addressing specification the Health Domain Name SHOULD be dedicated to this purpose and MUST include DNS RRs that specify either an A or a CNAME mapping to the HTTP server providing the RESTful API.

NHIN Direct HISP Address Directory

• DNS using the standard A or CNAME resource record type to associate the domain portion of the NHIN Direct Address (e.g., nhin.NelsonCardiology.example.com) with the HTTPS server address of the HISP.

NHIN Direct Backbone Protocol

• HTTP over TLS with a corresponding REST API.

Synopsis

The REST Implementation provides a uniform set of resources provided by each HISP.

The <base-uri> for the resources SHALL be https://<health-domain-name>/nhin/<version>, where <version> MUST represent the version of the REST Implementation supported. HISPs may support multiple versions of the API at the same time.

The <version> token for the version represented by this document SHALL be 'v1'

The <endpoint-base-uri> for endpoint specific resources SHALL be <base-uri>/<endpoint-path> where <endpoint-path> is in the following format:

endpoint-path = <health-domain-name> '/' <health-endpoint-name>

Where <health-domain-name> and <health-endpoint-name> are in the format described in the addressing specification.

The <messaging-base-uri> SHALL be <endpoint-base-uri>/messages

A full example of a Messaging Base URI is https://nhin.sunnyfamilypractice.example.com/nhin/v1/nhin.nelsoncardiology.example.com/janesmith/messages

HISPs SHALL provide the following resources at the URI created by appending the relative path to the Messaging Base URI:

Resource	Relative Path	Resource Description
Messages	/	The set of messages sent to the endpoint represented by <endpoint-path>
Message	/<message-id>	An individual message sent to the endpoint represented by <endpoint-path>
Message Status	/<message-id>/status	The status of a message represented by <message-id>

HISPs SHALL provide the following resource at the URI created by appending the relative path to the <endpoint-base-uri>:

Resource	Relative Path	Resource Description
Certificates	/certs	The set of public X.509 certificates possessed by the endpoint represented by <endpoint-path>.

<message-id> = <UUID>

Where UUID is defined by RFC 4122

HTTP methods and representations

Resource	Method	Headers	Representation
Messages	GET	Accept: application/atom+xml	An Atom feed of messages where each entry element contains an link element with a rel "alternate" attribute and an href attribute that contains the URI of the individual message
Messages	POST	Content-Type: message/rfc822	A health content container whose To: header contains the Health Internet Address represented in the <endpoint-path>. If the Destination HISP is identical to the Source HISP, creates the message and returns a resource whose Location header is the URI to the newly created message. If the To: header represents a remote address (served by a different HISP), will mirror this POST to the Destination HISP, and mirror the response to the Source
Message	GET	Accept: message/rfc822	A health content container representing the message at the specified resource
Message Status	GET	Accept: TBD	Returns a representation of the indicated message status
Message Status	PUT	Content-Type: TBD	Updates the selected message status. If the PUT is at the Destination HISP, mirrors the PUT operation to the Source HISP and mirrors the response to the Destination
Certificates	GET	Accept: application/atom+xml	An Atom feed of X.509 certificates possessed by the endpoint. Each feed entry contains a content element of type application/pkix-cert with a DER-encoded certificate as the content. For Atom compliance, the DER-encoded certificate content will be Base64 encoded

Message Status

In earlier versions of the specification the /messages/<message-id>/status resource was used to transmit message status back from the destination HISP to the sending HISP. This revision eliminates that use and the only remaining use of the /messages/<message-id>/status resource is between HISP and Destination.

Because the Abstract Model indicates message status must be made available to the sender, this specification embraces RFC 3798 for Message Disposition Notification. This is more effective than call between HISPs because it is initiated by the destination client software itself and can guarantee message display to a recipient.

As a side effect of removing the /messages/<message-id>/status call there is no remaining need for source and destination HISPs to have a consistent message identifier. Thus both source and destination HISPs are free to assign an individual unique identifier for each message and there is no requirement that the identifier be the same across HISPs.

Security and Trust

The REST implementation uses the S/MIME approach to fulfill the requirements agreed to in the Security and Trust Consensus v3 document. Specifically, message integrity and non-repudiation are achieved through a message-based S/MIME signature using the private key of the Source. The signature will oftentimes be executed by the Source HISP but may be executed by the Source (i.e., the provider) to the extent that PKI distribution extends to the Source. Verification of the signature at the Destination HISP (or possibly the Destination) requires the X.509 public certificate corresponding to the private key used to generate the signature. Message privacy is achieved through asymmetric encryption using the public X.509 certificate (public key) of the Destination. Decryption of the message is only possible using the private key of the Destination thus guaranteeing privacy in transit and at rest. The Source may encrypt, preventing the Source HISP from ever viewing non-encrypted PHI.

S/MIME expresses the X.509-based privacy and integrity features described above in standard multipart MIME types and headers. This fits well with the MIME-based Content Container Specification.

All X.509 public certificates are obtained through the Certificates REST resource specified above. Certificates may be issued at the organization or individual level.

The HISP-to-HISP transactions use TLS primarily to mitigate against on-the-wire snooping of metadata (such as To and From addresses) that could be considered Protected Health Information (PHI).

Mapping to Abstract Model Transactions

In the descriptions below, a truststore is a collection of "anchor" certificates (most often CA root certificates) that define the base level of certificate acceptance. A "TLS truststore" is a truststore used to verify certificates used as part of a TLS handshake. A "message send truststore" is a truststore used to verify certificates of Destination endpoints to which a Source is sending a message. A "message receive truststore" is a truststore used to verify certificates of Source endpoints from which a Destination is receiving messages.
 
 OPEN QUESTION: The TLS truststore (necessary for ensuring on-the-wire privacy for HISP-to-HISP transactions) requires (practically speaking) a single trust anchor (single CA). Only one certificate is needed per HISP so the burden of a central authority would be low. Is this acceptable? Could this be what the current NHIN Exchange CA evolves to be? Is it government run (by contract or otherwise)?
 
  There has been some discussion whether or mutual TLS authentication between HISPs is strictly necessary. Mutual authentication provides transport level blocking of a large class of attacks, but may impose additional burdensome CA requirements that can be eliminated with a one-way TLS model.
 
  Note that the mapping below illustrates a model where the HISP executes the S/MIME sign/encrypt/verify/decrypt functions on behalf of the Source and Destination. An alternative model places the PKI functionality in the Source or Destination itself.
 
 

Source to HISP

Configuration

• No configuration is necessary. The rules for formatting the URI, combined with the DNS mapping for the HISP's server name, are sufficient to allow the Source to reach the HISP.

Transaction 1.1: Source authenticates to HISP

• The Source constructs the server DNS name of its associated HISP. In most cases, this is a HISP-oriented name (e.g., hisp-a.com) and is typically not the DNS name of the Source itself (e.g., MetroCardiology.com).
• The Source MUST authenticate to the HISP using a mechanism that meets NHIN Direct minimum standards. Options include username/password via Basic HTTP Authentication, or presentation of a client certificate as part of a TLS handshake.
• The Source MUST employ a transport level privacy mechanism with the HISP server to render the message private while in transit. This MUST be done via TLS where the HISP presents a certificate during the TLS handshake. The Source MUST ensure that the HISP's TLS certificate is not expired, is not revoked, is issued from a trust anchor (typically represented by a CA root certificate) present in the TLS truststore of the Source. No hostname matching to the HISPs TLS certificate is done because TLS is being used primarily for privacy and not for authentication. The Source only presents a certificate during the TLS handshake if that is the Source authentication mechanism employed.

Transaction 1.2: Source sends NHIN Direct Message to HISP

• Source performs POST to /messages with an RFC 5322 message representation as specified by the Content Container Specification. The HISP assigns the message an identifier (currently UUID) and returns an HTTP "location" header including that identifier.

Transaction 1.3: Source receives message status information from HISP

• Source performs GET to /messages/<message-id>/status where <message-id> is the value returned by the HISP in transaction 1.2.

COMMENT: This transaction has been changed to indicate the source HISP assigns its own message id identifier. The only restriction on this identifier is that it be easily encoded onto the URI.

HISP to HISP

Transaction 2.1: Source HISP authenticates to destination HISP

• The source HISP executes a DNS query against the domain portion of the "To" RFC 5322 header (or the domain portion of the REST URL which will be identical). This may recurse through one or more CNAME lookups but the final result will be the IP address of the destination HISP server.
• The source HISP performs a mutual TLS handshake with the destination HISP. Both use their TLS certificate issued by the single NHIN TLS trust anchor (CA). Both HISPs validate that the presented certificates are not expired, are not revoked, and are issued from the common TLS trust anchor. No validation of any other certificate attributes is undertaken (i.e., no Subject CN check). Because S/MIME is used for Source to Destination authentication and privacy, the HISP-to-HISP transaction primarily requires on-the-wire TLS encryption and a coarse-grained authentication that each participating server possesses a certificate from the common TLS trust anchor (CA).
• Using the Certificates REST resource (as defined in this specification) associated with the "To" domain name, the source HISP looks up and retrieves the public keys (certificates) of the Destination. The certificates not issued from a trust anchor found in the source HISPs Message Send Truststore are discarded. Any remaining certificates (found in the truststore) are validated by ensuring that they are not expired, are not revoked, and contain a Subject CN that matches at least the domain name portion of the To address and possibly the endpoint and domain name portions of the To address.
• The source HISP signs (using S/MIME) the message using the private key associated with one of its public keys issued from a common trust anchor. The common trust anchor is discovered by inspecting the issuer of the Destination certificates obtained in the previous step.
• One of the validated Destination certificates is chosen and used to S/MIME encrypt the signed message.

Transaction 2.2: Source HISP sends NHIN Direct Message to destination HISP

• The source HISP performs POST to /messages with the encrypted and signed message produced in transaction 2.1.
• The destination HISP verifies the "To" address and persists the message using the unique value found in the Message-ID header.
• The destination HISP decrypts the message using one of its private keys.
• The destination HISP obtains the trusted certificates associated with the Source using the same Certificates resource technique described in transaction 2.1. One of the Source certificates is used to verify the Source signature.
• The destination HISP assigns a message identifier to the message and returns a URI including that identifier to the source HISP.

Transaction 2.3: Source HISP receives message status from destination HISP

• Message status from destination to client is handled via S/MIME encrypted MDN messaging in the RFC 5322 format. There is no difference to the HISP between a status message and a "reply message".

COMMENT: Transaction 2.3 from revision 1.2 has been revised. Status messaging is assumed to be handled by S/MIME protected MDN messages and there is no longer status messaging between HISPs other than normal S/MIME encrypted messaging.

HISP to Destination

Configuration

• No configuration is necessary. The rules for formatting the URI, combined with the DNS mapping for the Health Domain Name, are sufficient to allow the Destination to reach the HISP.

Transaction 3.1: Destination authenticates to HISP

• The Destination constructs the server DNS name of its associated HISP. In most cases, this is a HISP-oriented name (e.g., hisp-b.com) and is typically not the DNS name of the Destination itself (e.g., NelsonCardiology.com).
• The Destination MUST authenticate to the HISP using a mechanism that meets NHIN Direct minimum standards. Options include username/password via Basic HTTP Authentication, or presentation of a client certificate as part of a TLS handshake.
• The Destination MUST employ a transport level privacy mechanism with the HISP server to render the message private while in transit. This MUST be done via TLS where the HISP presents a certificate during the TLS handshake. The Destination MUST ensure that the HISP's TLS certificate is not expired, is not revoked, is issued from a trust anchor (typically represented by a CA root certificate) present in the TLS truststore of the Destination. No hostname matching to the HISPs TLS certificate is done because TLS is being used primarily for privacy and not for authentication. The Destination only presents a certificate during the TLS handshake if that is the Destination authentication mechanism employed.

Transaction 3.2: Destination lists available NHIN Direct Messages from HISP

• The Destination uses a REST GET request to retrieve an ATOM feed listing message URIs including the message id of each message.
• The default representation includes all new messages.
• The GET request may support the use of parameters to filter by status, message ID, date time, etc.

Transaction 3.3: Destination downloads NHIN Direct Message from HISP

• The Destination uses a GET request to retrieve a representation of an NHIN Direct Message from /messages/<message-id> as indicated in the ATOM feed message list.

Transaction 3.4: Destination updates message status with the HISP

• The Destination uses a PUT request to PUT a representation of the new message status to /messages/<message-id>/status. The body of the PUT is a simple string (ACK or NACK). Note that this status message is not sent back to the source, it is simply an indicator to the destination HISP that the message has been retrieved and should no longer be returned in the ATOM feed of new mesages.