Direct Health Messaging via Representational State Transfer over HTTP


Status of this Specification


This specification is in Draft state.

IPR Statement


By contributing to this specification, all contributors warrant that all applicable patient or other intellectual policy rights have been disclosed and that any of which contributors are aware of will be disclosed in accordance with the NHIN Direct project IPR Policy.

Abstract


This specification provides a mapping of the NHIN Direct Abstract Model to Representational State Transfer (REST) HTTP resources.


Introduction


Purpose


Requirements


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."

Synopsis


A Health Information Service Provider (HISP) is an organization that provides the services described in this document.

This specification provides a uniform set of resources provided by each HISP:

Resource
Resource Description
Messages
The set of messages sent to an address
Message
An individual message sent to an address
Message Status
The status of a message resource
Certificates
X509 certificates corresponding to an endpoint

These resources are mapped to a common set of relative URIs and HTTP methods on those URIs with well defined semantics as defined in this document.

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


Health data security and trust are provided by using S/MIME to sign and encrypt RFP 5322 Internet Message Format documents such that only authorized persons, and their explicitly authorized delegates may view messages, and such that they may verify the provenance of each message.

Terminology


The terminology adopted in the NHIN Direct Abstract Model, Content Container Specification and Addressing Specification is also adopted in this document.

URIs, Resources, and Protocol Operations


Base URI


health-domain-name = Health Domain Name

The definition of health-domain-name is provided in the addressing specification. Owners of the Health Domain Name MUST ensure the Health Domain Name is resolvable via the DNS to an HTTPS service running on the well-known HTTPS port.

base-uri = "https://" health-domain-name "/nhin" api-version

api-version = "v1"

The api-version MAY be incremented in later versions of this specification. All URIs using the api-version of v1 MUST correspond in format and semantics to this specification.

Non-normative examples of the Base URI include:

https://exchange.nelsoncardiology.example.org/nhin/v1
https://nhin.bigidnco.example.com/nhin/v1

Endpoint Base URI


endpoint-base-uri = base-uri "/" address-path
 
address-path = health-domain-name "/" health-endpoint-name

The definitions of health-domain-name and health-endpoint-name are provided in the addressing specification

The Endpoint Base URI provides resources corresponding to a valid Health Internet Address. This specification does not define implementation behavior to HTTP methods applied to the Endpoint Base URI.

Non-normative examples of an Endpoint Base URI include:

https://exchange.nelsoncardiology.example.org/nhin/v1/exchange.nelsoncardiology.example.org/jones
https://exchange.nelsoncardiology.example.org/nhin/v1/nhin.bigidnco.example.com/smith

Note in the second example that an Endpoint Base URI MAY be provided at a Health Domain Name that is different from the Health Domain Name for the endpoint. Examples of how why this may be done are provided in the Messages Resource section of this document.

Certificates Resource


certificates-uri = endpoint-base-uri "/certs"

The Certificates Resource provides representations of the public X.509 certificates corresponding to the Health Internet Address. Such certificates MAY be used to encrypt messages sent to the endpoint, verify signatures associated with the endpoint, or verify the details of the certificate.

Implementations MUST provide an Atom representation of the Certificates Resource in response to a GET request at that resource, when the GET request contains an Accept: header of application/atom+xml.

The Atom representation MUST be a valid Atom document, corresponding to RFC 4287. The Atom document MUST include one entry element per public certificate, and each entry MUST contain a content element of type application/pkix-cert, containing the DER-encoded certificate representation, Base64 encoded per the Atom specification.

Implementations MUST NOT authenticate, authorize, or otherwise filter GET requests to the Certificates Resource (as these are the public keys of the provider, there is value in making them generally and widely available).

A non-normative example of an Endpoint Base URI is:

https://exchange.nelsoncardiology.example.org/nhin/v1/exchange.nelsoncardiology.example.org/jones/certs

A non-normative example of a Certificates Resource Atom Representation is:

<?xml version="1.0" encoding="UTF-8"?>
<feed xml:lang="en-US" xmlns="http://www.w3.org/2005/Atom">
  <id>tag:drjones@nhin.happyvalleypractice.example.org,2005:certs</id>
  <link type="application/atom+xml"
             href="https://nhin.happyvalleypractice.example.org/nhin/v1/nhin.happyvalleypractice.example.org/drjones/certs"
             rel="self"/>
  <title>Certificates for drjones@nhin.happyvalleypractice.example.org</title>
  <updated>2010-06-09T17:59:35Z</updated>
  <entry>
    <id>tag:drjones@nhin.happyvalleypractice.example.org,2005:certs/438678246</id>
    <published>2010-05-26T18:34:38Z</published>
    <updated>2010-05-26T18:34:38Z</updated>
    <title>Certificate for drjones@nhin.happyvalleypractice.example.org</title>
    <summary>Certificate for drjones@nhin.happyvalleypractice.example.org</summary>
    <author>
      <name>drjones@nhin.happyvalleypractice.example.org</name>
      <email>drjones@nhin.happyvalleypractice.example.org</email>
    </author>
    <content type="application/pkix-cert">MIIChDCCAe0CAQEwDQYJKoZIhvcNAQEFBQAwgYMxCzAJBgNVBAYTAlVTMQsw
CQYDVQQIEwJDQTEQMA4GA1UEBxMHT2FrbGFuZDEUMBIGA1UEChMLTkhJTiBE
aXJlY3QxFDASBgNVBAMTC05ISU4gRGlyZWN0MSkwJwYJKoZIhvcNAQkBFhph
cmllbi5tYWxlY0BuaGluZGlyZWN0Lm9yZzAeFw0xMDA1MjAxNzM0MjdaFw0y
MDA1MTcxNzM0MjdaMIGQMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExEDAO
BgNVBAcTB09BS0xBTkQxFjAUBgNVBAoTDUxpdHRsZSBISUUgQ28xHzAdBgNV
BAMTFkxpdHRsZSBISUUgQ28gb3BlcmF0b3IxKTAnBgkqhkiG9w0BCQEWGmFy
aWVuLm1hbGVjQG5oaW5kaXJlY3Qub3JnMIGfMA0GCSqGSIb3DQEBAQUAA4GN
ADCBiQKBgQClEcq+PnXMMfTKjEXqn1n7OxyhTxxsjTHPXJ/Mp/uu2tHcrF5z
HHs/uRChEP5XODwYyfXjJM5+5IVgJmKEhmaisxSPA/bOc4UVcLcyvsPr43f3
0Ua0WKDn30js4UUr+JqBS70yyfqOxWSmZJJo43u42q0+AfQQt4dw8tJyzmgE
9wIDAQABMA0GCSqGSIb3DQEBBQUAA4GBACEEhfU0ibFM73emNPpP5sBZ0CSk
X535UhBPViVUV5XVQYJ57d3L0yZQRQrSCOSOWQ9bN2eszVslh1D33YmonW1n
py8W84AshDGYYp4KjHEeQr+pQfoUm46+e1tOC22KNeJi7YhDs2yqD7b4mDr6
WDtMSuewfapVEJdzsTDTRdWz
</content>
  </entry>
</feed>

Messages Resource


messages-uri = endpoint-base-uri "/messages"

The Messages Resource represents messages sent to the specified Health Internet Address.

Note that the endpoint-base-uri MAY include different health-domain-name values for the HTTPS server domain and the Health Internet Address domain.

A non-normative example of a URI serving this need would be:

https://exchange.nelsoncardiology.example.org/nhin/v1/nhin.bigidnco.example.com/smith/messages

This URI would allow operations by jones, an addressable endpoint at exchange.nelsoncardiology.example.org with respect to smith, an addressable endpoint at nhin.bigidnco.example.com, including creating a message resource that is sent by the Source HISP to nhin.bigidnco.example.com.

Messages List Operation


An authenticated and authorized GET Request to the messages-uri SHALL provide a list of messages sent to the Health Internet Address.

The following protocol operations MUST be provided by implementations of this specification in response to a GET Request to messages-uri:

Accept
Conditions
Response Status
Response Content
application/atom+xml
Authenticated and authorized request
200
A Messages List representation formated as described below containing references to the NEW individual Message resources sent to the Health Internet Address and available for access
Any
Not authenticated
401
None

Implementations MUST handle authenticated but not authorized requests. Clients SHOULD be prepared to handle status codes in the 400 range or empty documents. Implementations MAY provide other representations in response to different Accept header values.

Implementations MAY support access to Messages Lists representing status values other than NEW through query parameters or subresources and MAY support other representations.

Messages List Atom Representation


The Atom representation of a Messages List MUST conform to the following constraints:

  • The Atom feed MUST be a valid Atom feed, corresponding to RFC 4287
  • The Atom feed MUST contain one entry element for each listed Message resource
  • The entry element MUST contain a link element with a rel attribute of value "alternate" and an href attribute providing the URI of the listed Message resource

Implementations MAY provide additional information in the Messages List Atom Representation.

Message Create Operation


An authenticated and authorized POST Request to the messages-uri SHALL create a message resource (possibly at a remote HISP).

The semantics are to create a message to the address represented by the address-path. If a Source wishes to send a message to multiple destinations, the Source MUST create a message resource for each receiver.

The following protocol operations MUST be provided by implementations of this specification in response to a POST Request to messages-uri:

Content-Type
Conditions
Response Status
Response Content
message/822, non-signed and encrypted body
An authenticated and edge role authorized user who is the message sender, HISP has created the message, either locally or through synchronous remote creation
201
Location header providing the message-uri of the created resource
message/822, non-signed and encrypted body
An unauthenticated edge role user
401
None
message/822, non-signed and encrypted body
An authenticated but unauthorized (e.g., not the message sender) edge role user
403
None
message/822
Message can not be parsed to verify required headers
400
None
message/822, application/pkcs7-mime enveloped encrypted signed body
Receiver can verify the message, or is a Source HISP and successfully delivers to a Destination HISP, or Destination prefers to receive signed and encrypted messages for local verification
201
Location header providing the message-uri of the created resource
message/822, application/pkcs7-mime enveloped encrypted signed body
Destination HISP can not decrypt message or, once decrypted, can not verify the message signature
403
None

The following protocol operation MAY be provided by implementations that provide asynchronous delivery. Clients MUST be prepared to receive a 202 status.

Content-Type
Conditions
Response Status
Response Content|
message/822
The HISP has accepted the message and may deliver asynchronously
202
Location header providing the message-uri of the resource to be created; the status resource MUST be immediately available to allow the Source to check delivery and receipt status

Because the message-uri contains a message-id that is supplied by the message/822 content body, the following operations MUST be supported:

  1. A Source HISP MUST accept message/822 content that has a valid message-id supplied by the Source
  2. If the Source HISP receives message/822 content that does not have a message-id, the Source HISP MUST create a valid message-id and associated message/822 header
  3. A Destination HISP receives a message/822 that has been signed and encrypted, and MUST verify the presence of a valid message-id and MUST NOT create a message-id if not present. Instead, it MUST respond with an error status.

In cases where the Source and Source HISP are separate entities, and the Source HISP has been delegated by the Source to perform signing and encryption, the Source will POST the message representation to the Source HISP with an address-path of the address to which the message is being sent. The Source HISP will then sign and encrypt and either synchronously POST the message representation to the same path portion of the messages-uri to the Destination HISP by using the health-domain-name of the addressed Health Internet Address in the domain portion of the messages-uri, and echo the HTTP status and required response content back to the Source; or will queue the message for asynchronous delivery.

The overall flow for successful synchronous delivery is:
 
Source     Source          Destination
|            HISP               HISP
|----POST----> |                 |
|              |                 |
|              |---              |
|              |  |              |
|              | Sign            |
|              | and             |
|              | encrypt         |
|              |  |              |
|              |---              |
|              |                 |
|              |------POST------>|
|              |                 |---
|              |                 |  |
|              |                 | Decrypt
|              |                 | and
|              |                 | verify
|              |                 |  |
|              |                 |---
|              |<---Response-----|
|              | 201 + Location  |
|<--Response---|                 |
|201 + Location|                 | 

The overall flow for successful asynchronous delivery is:
 
Source     Source          Destination
|            HISP               HISP
|----POST----> |                 |
|              |                 |
|              |---              |
|              |  |              |
|              | Sign            |
|              | and             |
|              | encrypt         |
|              |  |              |
|              |---              |
|<--Response---|                 |
|202 + Location|                 | 
|              |                 |
|              |------POST------>|
|              |                 |---
|              |                 |  |
|              |                 | Decrypt
|              |                 | and
|              |                 | verify
|              |                 |  |
|              |                 |---
|              |<---Response-----|
|              | 201 + Location  |
|              |                 |
|-----GET----> |                 |
|    Status    |                 |
|              |                 |
|<--Response---|                 |
|200 + Status  |                 | 


Assuming the Health Endpoint Name jones at Health Domain Name exchange.nelsoncardiology.example.com is initiating this transaction, the first POST in the sequence (from Source to Source HISP) would be to:

https://exchange.nelsoncardiology.example.org/nhin/v1/nhin.bigidnco.example.com/smith/messages

And the second POST (from Source HISP to Destination HISP) would be to:

https://nhin.bigidnco.example.com/nhin/v1/nhin.bigidnco.example.com/smith/messages

Other variations are possible:

  1. If both addresses are served by the same HISP, the Source will POST to the Source HISP, which will create the message locally and format the response accordingly.
  2. If the Source can sign and encrypt, it may follow the above flow (in which case the Source HISP will replay to the Destination HISP without further processing) or may POST directly to the Destination HISP

The value of the location header returned by the Source HISP in the full flow will be to a URI whose host is the Source's Health Domain Name, rather than the Destination's Health Domain Name. This allows the Source to query the Status Resource at a host for which the Source has authenticated credentials.

Message Resource


message-uri = messages-uri "/" message-id
 
message-id = uuid "@" health-domain-name

The production rule for uuid is supplied by RFC 4122

The message-id in the URI MUST be the same message-id as found in the Internet Message Format Message Representation. (Note that, per RFC 5322, the content of the message-id does not contain the angle brackets found in the Message-ID RFC 5322 header.)

Message Retrieve Operation


An authenticated and authorized GET Request to the message-uri SHALL return a Message Resource representation if the server supports the representation accepted by the user agent.

The following protocol operations MUST be provided by implementations of this specification in response to a GET Request to the message-uri:

Accept
Conditions
Response Status
Response Content
message/822
User is authenticated and authorized, message exists
200
The response body SHALL contain the message/822 representation of the requested message
Any
User is not authenticated
401
None
Any
User is authenticated but not authorized
404
None
Any
Message ID does not exist
404
None
Any
Server does not support the content type requested by the User Agent with the Accept header
406
None

Message RFC 822 Representation


See Content Container Specification

Status Resource


status-uri = message-uri "/status"

Status Retrieve Operation


An authenticated and authorized GET Request to the status-uri SHALL return a Status Resource representation if the server supports the representation accepted by the user agent.

The following protocol operations MUST be provided by implementations of this specification in response to a GET Request to the status-uri:

Accept
Conditions
Response Status
Response Content
message/rfc822
User is authenticated and authorized, message exists
200
The response body SHALL contain the MDN representation of the requested status
Any
User is not authenticated
401
None
Any
User is authenticated but not authorized
404
None
Any
Message ID does not exist
404
None
Any
Server does not support the content type requested by the User Agent with the Accept header
406
None

Status Update Operation


An authenticated and authorized PUT request to the status-uri SHALL update the message status if the server supports the representation supplied by the user agent.

The following protocol operations MUST be provided by implementations of this specification in response to a PUT Request to the status-uri:

Content-Type
Conditions
Response Status
Response Content
message/rfc822, unsigned and unencrypted message/report body
User is authenticated and authorized, message Source is local to the HISP or message Source is remote and status is updated remotely through a successful synchronous operation
200
None
signed and encrypted body
Status is decrypted and verified successfully by Source HISP or Source prefers to decrypt and verify locally
200
None
signed and encrypted body
Status can not be decrypted or signature can not be verified
403
None
unsigned and unencrypted body
User is not authenticated
401
None
unsigned and unencrypted body
User is authenticated but not authorized (i.e., not message receiver)
404
None
Any
Message ID does not exist
404
None


The following protocol operation MAY be provided by implementations that provide asynchronous delivery. Clients MUST be prepared to receive a 202 status.

Content-Type
Conditions
Response Status
Response Content

The Destination HISP has accepted the status, the Source HISP is not the Destination HISP, and the Destination HISP will deliver asynchronously
202
Location provides a single purpose URI that may be used to find the HTTP status of the asynchronous transaction. That URI MUST be unique to the Status Update Operation, MUST NOT follow a production rule otherwise specified in this document, but otherwise MAY be any valid URI. In response to a GET or HEAD request to that URI, the URI MUST return either status 202, to indicate that the status update has not been delivered, or the status returned by the Source HISP. The response MUST be used solely for the purposes of discovering the status of the original PUT request, and MUST NOT return any body content or headers that contain Protected Health Information.


The overall flow for successful synchronous delivery is:
 
Source     Source          Destination
|            HISP               HISP
|-----PUT----> |                 |
|              |                 |
|              |---              |
|              |  |              |
|              | Sign            |
|              | and             |
|              | encrypt         |
|              |  |              |
|              |---              |
|              |                 |
|              |-------PUT------>|
|              |                 |---
|              |                 |  |
|              |                 | Decrypt
|              |                 | and
|              |                 | verify
|              |                 |  |
|              |                 |---
|              |<---Response-----|
|              |    200          |
|<--Response---|                 |
|   200        |                 | 


The overall flow for successful asynchronous delivery is:
 
Source     Source          Destination
|            HISP               HISP
|-----PUT----> |                 |
|              |                 |
|              |---              |
|              |  |              |
|              | Sign            |
|              | and             |
|              | encrypt         |
|              |  |              |
|              |---              |
|<--Response---|                 |
|202 + Location|                 | 
|              |                 |
|-----HEAD---->|                 |
| to Location  |                 |
|<--Response---|                 |
|   202        |                 | 
|              |-------PUT------>|
|              |                 |---
|              |                 |  |
|              |                 | Decrypt
|              |                 | and
|              |                 | verify
|              |                 |  |
|              |                 |---
|              |<---Response-----|
|              |    200          |
|-----HEAD---->|                 |
| to Location  |                 |
|<--Response---|                 |
|   200        |                 | 
|              |                 | 


Status Resource MDN Representation


The Status Resource MDN Representation SHALL be an RFC 3798 Message Disposition Formatted Internet Message Format document.

The following clarifications and changes are applied in the use of RFC 3798 by this document:

disposition-type = "displayed"
                 / "dispatched"
                 / "processed"

Note that the production grammar for RFC 3798 removes the processed and dispatched values from the disposition-type definition, but refers to them in the RFC text.

The disposition-type of dispatched SHALL be interpreted to mean that the message has been accepted by the Source HISP but has not been delivered to the Destination HISP.

The disposition-type of processed SHALL be interpreted to mean that the message has been accepted by the Destination HISP but has not been delivered to the Destination.

The disposition-type of displayed SHALL be interpreted to mean that the message has been delivered successfully to the Destination.

The disposition-type of deleted, defined in RFC 3798, is not defined in this specification.

When the disposition-modifier is error, the error-field MUST be provided, and SHOULD provide error text that is formatted according to the error handling rules for the content that was transmitted (for example, HL7 V2 error reporting for HL7 V2 messages).

Source and Destination Authentication to HISP


HISP implementations MUST support the combination of HTTP Basic authentication combined with mutual TLS with a client certificate, and MUST practice strong security measures to keep the authentication factors secure. Implementations MAY support additional authentication mechanisms defined by policy.

Internet Message Format Encryption and Signature Operations


HIGH LEVEL FLOW: TODO: BETTER DETAIL

Follows RFC 5751. Also MUST include the subject header in the content package to be signed and encrypted.

Send

  1. The receiver's certs resource is queried to discover the current certificates in use
  2. The receiver's certificates are examined to determine validity and common anchors with the sender's supported certificates
  3. A receiver certificate + sender certificate and key pair are selected that have a common anchor.
  4. If no common anchor is discovered, error
  5. The content package (the body with the content-* headers and the subject header) is extracted
  6. The content package is signed with the receiver certificate
  7. The content package is encrypted with the sender's private key and certificate

Receive


  1. The sender's certs resource is queried to discover the current certificates
  2. The sender's certificates are examined to determine validity as of the date-time of the message transmission
  3. All sender certificate + receiver certificate and key pair are selected that have a common anchor
  4. If no common anchors are discovered, error
  5. For each sender certificate, attempt to decrypt the message and test if the message has a valid signature
  6. If so, test the signature's validity with each of the matching receiver certificates + key pair
  7. If the message is successfully decrypted and signature verified, success
  8. If all sender certificates are exhausted, error

Note that the sender algorithm MAY be applied either at the Source or the Source HISP, and the receiver algorithm MAY be applied at either the Destination HISP or the Destination. The sender algorithm MUST be applied prior to transfer to the Destination HISP.

Security Considerations


TO BE COMPLETED AFTER RISK ANALYSIS.

Key considerations:

  1. All transactions (Source/Destination to HISP and HISP-HISP) MUST be over TLS encrypted channels
  2. Implementations MUST check TLS certificates for validity
  3. Implementations MUST verify certificates used for encryption and signature verification.

Examples


This section is non-normative.


Authors


References


Bradner, Key words for use in RFCs to Indicate Requirement Levels, RFC 2119
Nottingham & Sayre, Atom Format, RFC 4287
Network Working Group, Internet X.509 Public Key Infrastructure: Operational Protocols: FTP and HTTP, RFC 2585
Leach et al., A Universally Unique IDentifier (UUID) URN Namespace, RFC 4122
Crocker, Augmented BNF for Syntax Specifications: ABNF, RFC 5234
Hansen & Vaudreuil, Message Disposition Notification, RFC 3798
Ramsdell & Turner, S/MIME 3.2 Message Specification, RFC 5751


Copyright


By contributing to this specification, all contributors agree to license contributions according to the Creative Commons Attribution 3.0 License which is incorporated into this document by reference.