HL7 over HTTP is an initiative to provide a standardized transport mechanism to send HL7 v2 messages over a network using the HTTP protocol.
Requirement levels (MUST, SHOULD, etc.) are used according to RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt).
HL7 over HTTP is a transport mechanism which uses the Hypertext Transfer Protocol (as defined in RFC 2616) to transmit HL7 artifacts (for example messages, documents, resources).
HL7 over HTTP is intended as an alternative to the traditional Minimal Lower Layer Protocol (MLLP), and provides a number of key improvements:
HL7 over HTTP uses the standard HTTP/1.1 protocol (RFC 2616) as a mechanism to transfer a raw HL7 message using standard HL7 encoding (i.e. "vertical bar" or XML) encoding to a destination, and then to receive a response to that message.
HL7 over HTTP is a constraint of the HTTP/1.1 specification. This means that it should be possible to configure any conformant HTTP implementation to comply with this specification, but it does not mean that any conformant HTTP implementation is necessarily compliant with HL7 over HTTP.
HL7 over HTTP does not extend HTTP/1.1 in any way. There are no protocol features in the specification which are not a part of the source specification.
All recommended and required constraints on the HTTP specification are defined in the following sections.
Every interaction consists of a request message and a response message. In a normal message exchange, the receiving system opens a server socket. The sending system then connects to that socket and uses the HTTP POST action to transmit a message. The receiving system then replies with an HTTP 2xx success, and transmits the response message (typically an HL7 Acknowledgement/ACK message) in the body of the response.
The following figure shows a typical message exchange:
The request message SHALL include a universal resource identifier (URI), per the HTTP specification. This URI SHOULD indicate the appropriate "interface" for the message. This is analogous to the port number in a standard MLLP configuration.
For example, a receiving laboratory information system application might open an
HTTP server on port 1234 which is capable of receiving several types of data. The
sending system could then address ADT data to the receiving system's ADT queue using
the following POST request
POST /Lab_Info_System/ADT HTTP/1.1
An implementing receiving system MAY also choose to use a separate port for each interface, as is the norm for MLLP interfaces. This is acceptable and will work, but is not desirable as it is not common practise in HTTP applications.
The request message and the response message SHALL include a Content-Type header, which indicates the type of data being transferred. The following MIME types apply:
Non-error response messages being transmitted by a server MUST use the same content type as the corresponding request message. In other words, if a request message uses XML encoding, the corresponding response message MUST also use XML encoding. See section 2.6 Response Codes for more information about response codes for error handling.
HL7 over HTTP message payloads SHALL use the UTF-8 character encoding scheme.
In addition, both the request message and the response message SHALL include a charset definition which indicates which character encoding is being used for the message body.
The HL7 v2.x specification allows the character encoding to be specified in MSH-18. When a message is sent using HL7 over HTTP, this value shall be either UNICODE UTF-8 (according to the designation in table 211), or shall not be present (indicating ASCII, a proper subset of UTF-8). When a message is received using HL7 over HTTP, this value SHALL be ignored, and the character encoding specified in the HTTP "Content-Type" header MUST be observed instead.
When a message is sent using HL7 over HTTP, the sending application MAY choose to use the value in MSH-18 to inform the choice of charset, although it is not obligated to do so.
An example follows which shows the Content-Type header used to indicate that a "vertical bar" encoded message is being transmitted.
Content-Type: application/hl7-v2+er7; charset=utf-8
Request messages and Response messages SHALL provide a date header which informs the other party of the time that the message transmission was started.
Note that the HTTP Date header is not required to agree with the HL7 message timestamp found in the HL7 v2.x message within MSH-7.
The recommended use of these two dates is as follows:
An example follows which shows a date header:
Date: Tue, 15 Nov 1994 08:12:31 GMT
If a receiving application is able to respond to a request by producing an HL7 response payload, the HTTP status code returned MUST be a code of HTTP/1.1 2xx. This response payload is typically an HL7 ACK message, but other message types may apply to certain exchanges (e.g. RSP_xxx)
The HL7 protocol defines four non successful acknowledgement codes:
When a receiving application produces an HL7 response payload containing one of these status codes, this is considered a successful interaction at the transport layer, and response code of "HTTP/1.1 2xx" MUST be used.
Non 2xx status codes are reserved for use in cases where the message was not understood, could not be delivered to the receiving application layer, or the receiving application layer failed to process the message due to an unexpected error condition.
If the response status is not HTTP 2xx, the content type MUST NOT be an HL7 payload type. Instead, a textual representation of the transport level error must be provided using an appropriate content type.
Many HTTP implementations will return a content type of "text/html" to provide a nicely formatted error message for internal server errors and invalid addressing. Because HL7 messaging is typically processed between servers, with no HTML browser present, implementers may consider using a content type of "text/plain" in order to increase readability.
An example follows which illustrates a transport level problem.
If no HL7 response message is generated and the receiving application wishes to indicate an error, the receiving application MAY use any content type to encode the response message. Note that using a content type of text/plain may increase readability within system logs.
HL7 defines a number of messages which are designed to be sent to a receiving system in a query/response mode, where the receiving system receives the query message and responds with a message containing data which fulfills the query.
When a receiving system responds to a query, a normal HTTP 2xx response code MUST be used in all cases where the application response is an HL7 message.
This specification defines three security profiles which offer various levels of security. Each may be appropriate depending on the needs of the application.
HTTP is a widely used protocol across a vast number of different network topologies and secure environments. As such there are many widely used techniques for securing HTTP traffic. Each mechanism has its own tradeoffs in terms of the type of security it provides (encryption, non-repudiation, tracking, etc.) and in terms of the ease of implementation.
Because HL7 transactions often contain data which is considered highly sensitive, it is important to consider the implications of the security mechanisms in place between systems which exchange HL7 data.
While implementors MAY choose to implement any security techniques which are considered appropriate for the specific implementation, the HL7 over HTTP security profiles take advantage of commonly used techniques for securing the HTTP protocol, and provide a testable and commonly understood definition for security.
These profiles are designed to have strict requirements, such that they may be tested in a conformance environment to ensure compatibility.
It is important to select a security model which are appropriate to the specific application being used and the network it is deployed to. The following table shows the security characteristics of the security profiles described in this specification.
|Encryption (Prevents Eavesdropping)||Server Authentication (Ensures Client Identity)||Client Authentication (Ensures Server Identity)|
|Level 1||No||Yes (Very weak)||No|
|Level 3||Yes||Yes (Very strong)||Possible|
Security Profile Level 0 (referred to hereafter as "Level 0") simply refers to any situations where the profiles below are not used.
Note that the use of these security profiles is not mandatory in order to be conformant to the HL7 over HTTP specification. There are many situations where the use of this type of transport encryption is not neccesary due to network design or other aspects of the solution design.
Security Profile Level 1 (referred to hereafter as "Level 1") consists only of a security token which allows the receiving system to verify the identity of the sending system.
Level 1 does not include any encryption mechanism, and therefore does not protect messages in transit against eavesdropping or tampering. This is an important consideration when choosing a security profile, and Level 1 should therefore only be used within closed/protected networks.
To implement Level 1, the sending application MUST include a header called "Authorization", containing a basic authorization token as described in Section 11.1 of RFC 1945. The basic authorization token consists of the token "Basic", followed by a space, and then followed by a token in the form "username:password" which has been base64 encoded.
The receiving application must be capable of validating this authorization token. If the credentials can not be successfully validated, the receiving application SHALL return an HTTP response code of "HTTP/1.1 401 Unauthorized".
The following is an example of an authorization header for Level 1:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
The sending application MUST use basic authorization in order to be conformant to Level 1. Other types such as "digest access" authorization MUST NOT be used.
Security Profile Level 2 (referred to hereafter as "Level 2") consists of a security token used to authenticate the client with the server, but additionally adds an encrypted connection.
Sending applications and receiving applications implementing this profile MUST implement all functionality described in Security Profile Level 1.
Sending applications and receiving applications implementing this profile MUST additionally support the ability to communicate using HTTPS, i.e. using Transport Layer Security (TLS), version 1.2 (RFC 5246, http://www.ietf.org/rfc/rfc2246.txt) or later. Transport Layer Security provides the possibility for end-to-end encryption.
The certificates used SHALL be X.509 certificates based on RSA key with a key length in the range between 1024 and 4096. Supported cipher suites SHALL include TLS_RSA_WITH_AES_128_CBC_SHA, other ciphers MAY be chosen based on site-specific policies.
In addition, sending applications implementing this profile MUST be capable of importing a public key in order to support the use of self-signed certificates.
Sending applications and receiving applications implementing this profile MUST support mutual authentication as specified in the TLS specification. Here, the client additionally presents a X.509 client certificate to the server in order to authenticate its access.
Where Level 3 is being used, HTTP Basic Authentication (specified in Level 1) MAY be omitted.
The following section of this specification provides further details for specific implementation considerations.
HTTP implementations are commonly multi-threaded, particularly in HTTP server implementations. This can present a risk that messages will be processed in a different order than the one in which they were generated. Because message sequence is often important in HL7 v2.x transactional messaging, implementers should consider how to ensure that messages are processed sequentially. In the event that conventional sequence management cannot be employed then the sequence number protocol SHALL be used.