software

printer friendly version of this page

The Indivo Server

The Indivo server is comprised of many interacting modules and layers. These modules and layers are discussed below, along with a description of the communication protocol that clients will use to contact the server.

Actors

The Indivo actor is a user (or agent) of the Indivo system. Each actor in the system is assigned various attributes when her record is created. These attributes include roles, group memberships, and proxy representations. A role in Indivo is associated with certain privileges like the ability to create records, read records, and add or update elements in records. For instance, an actor logged in with a "patient" role may have the ability to read and update her own record, but not be able to create new records for others. An important note about privileges is that even though someone may have the privilege to perform an action in some records, that action may be restricted by patient-defined access policies in any particular record. In the case where an actor has multiple potential roles (a doctor can also be a patient), the actor must designate the appropriate role upon login.

Group memberships do not have privileges associated with them. Their usefulness resides in the ability for actors in the system to set access policies on their own records to allow or forbid certain actions to members of a particular group. For instance, an actor might want to specify a policy in her record that allows all providers in the allergy department at her health clinic to add documents classified as allergy documents. This can easily be accomplished if all of the providers have a group membership that identifies them as part of that department.

Finally, when an actor A is acting as a proxy for another actor B, all access policies on a record that are relevant to actor B are now relevant to actor A. This means, that even though doctor A does not have any access policies on a patient's record that allow an update, since there are policies that allow doctor B to update, they would allow A to update as a proxy. Access decisions are discussed in more detail in the section describing the authorization module.

Clients

A Indivo client is any software process adherent to the IndivoTalk protocol (a variant of web services) and that interacts with the Indivo system via a Indivo server. Examples of Indivo clients include a Java application that provides a patient with a browseable view of their entire record and control of read/write/update permissions; a Fax server that allows images of paper documents to be faxed into the Indivo record (upon authentication and authorization); and a polling application that reads a population of Indivo records. The implementation language or platform for the client is immaterial so long as the Indivo client can communicate with the Indivo server via the standard IndivoTalk protocol. A Indivo client can be a software agent with any function so long as IndivoTalk is adhered to, and the authentication and authorization components of the protocol are observed.

The IndivoTalk Protocol

IndivoTalk is a communication protocol, based on XML messages described in a World Wide Web Consortium (W3C) XML schema, and a request-response interaction between a client and a server. The IndivoTalk protocol is kept generic so that it can be easily expanded as new actions and results of those actions are defined and added to deployed Indivo servers. The generic IndivoTalk request contains an optional session ticket that identifies the actor making the request, an action wrapper that has a description of the action that the client wants the server to perform, and all the necessary information that the server needs to process the action. Examples of this information include credentials for an authentication action, patient records to be created, query strings describing records to be read, and other information relevant to the type of action.

The server responds to an action with a response that has structure similar to that of the request but with some slight differences. Instead of an action wrapper, the response contains a result wrapper that has a description of the result being returned and the result itself (specific to the action requested). The response also includes a status message indicating whether the action was performed successfully or not. Both request and response structures include attributes that identify themselves, the IndivoTalk schema version that defines their structure, and the time of issuance.

In the Indivo reference implementation, we have defined six actions and their corresponding results. The actions include creating a new record, reading an existing record, authenticating to the Indivo server, querying for a list of records, adding a document to a record, and updating a document within a record.

Resources

The Communication Layer

The communication layer is responsible for communication over various Internet protocols and the unmarshalling and marshalling of IndivoTalk messages. That is, when a request is made to the server, the communication layer extracts the XML contained in the request, converts it into a usable program object, and passes it along to the action response layer. Once the action response layer has returned the appropriate object representing the XML response, the communication layer marshals the object into the protocol's response that is sent back to the requesting party.

The reference implementation of the communication layer is handled by a Java 2 Enterprise Edition (J2EE) compliant Servlet. The Servlet technology provides the ability to send and receive IndivoTalk messages over the Secure Hyper Text Transfer Protocol (HTTPS) communication protocol. The advantages to this include inherent encryption of the IndivoTalk messages through the use of HTTPS and easy manipulation of the request through the existing Java Servlet application programming interface.

Although we have chosen JAVA Servlets for the Indivo reference implementation, other developers can implement the communication layer within other application frameworks and maintain interoperability with other Indivo servers and clients so long as adherence to the IndivoTalk protocol is maintained.

The Action Response Layer

The action response layer contains the logic for processing registered actions and maintains information about actor sessions. Actions are registered during startup when the controller module of the layer is initialized. During the initialization phase, the controller reads a configuration file that contains the information necessary to instantiate modules that are registered to handle a particular action. The information used in instantiation typically includes definitions of data stores, authorization engines, and the type identification of actions that the module will handle. When an action request is sent to the server and passed on to the action response controller, the controller delegates the processing of the action to the registered module. The modules are responsible for enforcing their own security policies, and returning a result consistent with the action. Since the modules are responsible for their own security, it is essential that the server administrator understand and trust what each module is doing. With this modular approach, the Indivo server can be used in any web services environment (not just specific to personally controlled records) since the logic of responding to actions is contained in these fully pluggable modules. In our reference setup of Indivo for personally controlled health records we include modules for authenticating, creating new records, adding new documents to existing records, updating existing documents in records, reading a record, and querying for sets of records. Each of these modules utilizes the data store and authorization engine discussed in further detail below. Upon receipt of an action, the reference modules extract the relevant information, and construct authorization requests for the authorization engine. If the engine permits the request, the modules construct a result based on the type of action and information that they can retrieve from the data store.

The final feature of this layer is a pluggable action extension mechanism. The mechanism is pluggable in the same manner as the action module is in that extensions are registered during the server initialization phase. Also like the action modules, extensions register for particular action events. The difference in the behavior of the extension is that it executes its task after the action module has finished, and the execution is asynchronous with the request. That is, a response is sent to the request in parallel with the execution of the extension process. To date, simple extensions have been used to report on the status of the server but more complicated extensions are being planned. One possible extension would replicate actions to a backup Indivo server.

The Authorization Module

The authorization module contains the logic for determining whether an actor is allowed to perform a particular action on a particular record or record element. Authorization for an action can be based on either the policies of the action responder processing the action, the policies of the record (if any) that the action is being performed on, or a combination of both. In order to process these authorization requests, the module must be initialized in such a way that it can locate the relevant policies. In the case of locating responder policies, the module is initialized with a list of files that each contains one or more policies. In the case of locating individual record policies, the module is initialized with the data store that the records are in. A typical action responder will have two instantiations of the authorization module (one to enforce the responder policies and one to enforce the record policies) and be coded to combine the results in a meaningful way.

The Indivo reference authorization module is based on the Organization for the Advancement of Structured Information Standards (OASIS) extensible access control markup language (XACML) specification and utilizes Sun Microsystems's open source XACML library to implement the necessary functionality. XACML is an OASIS standard that describes both a policy language and an access control decision request/response language (both encoded in XML). The policy language provides the ability to describe detailed and complex access control based on the actor making the request, the action being taken, and the resource to which the action will be applied.

A major advantage to this access control model is that it is not based on a fixed hierarchy of access levels. This is especially important in a personally controlled health record such as Indivo where different record owners may have different preferences concerning what individuals and groups will be allowed to view their data. That is, we explicitly reject the notion that there is a single, natural, or even fixed personal hierarchy of privacy. Depending on the idiosyncratic concerns of the individual, different items will have different privacy policies that differ from those of others and even from those at a different time in that individual's history. For example, HIV status may be of lesser concern to some individuals than the hospital at which they obtain their care. At other stages of their life, all but their resuscitation orders may be considered private by that individual.

Another advantage to using the XACML policy model is that it enables the enforcement of policies at a fine-grained level. That is, policies can be written that apply to individual documents within the record, not just on the record itself. For instance, the result of reading a record for which access is denied to certain documents will appear as if those documents do not exist.

The Data Store Layer

The Data store layer is responsible for housing all of the records that the server needs access to. The layer was designed in a pluggable fashion such that a number of different types of stores can be configured for the server to use. Interaction with a store that is not currently supported by the system can be accomplished using the Indivo API. The API contains a Java interface that defines the method calls that the Indivo server uses when communicating with the back-end store. By writing a Java class that implements the IndivoStore interface with methods that perform the correct operations, a developer can enable the use of any back-end store.

There are many possibilities for a suitable data model for Indivo records, each with its own advantages and disadvantages. Perhaps the simplest model is to store all the records as a single, encrypted xml BLOB. The advantage to this scheme lies in its simplicity and its inherent privacy (viz. individual records are not identifiable without decrypting the entire store.) The disadvantages to this model lie in the performance overhead incurred in decrypting a large BLOB each time that any action needs to be performed on the data. A model that maintains the advantage of security and privacy involves maintaining a single, encrypted record BLOB for each user. The BLOB is indexed by a one-way hash (SHA-1, etc) of the user's name. This allows for faster lookup of individual records, while still protecting the information contained within them. However, performance is still an issue when querying the store for records that contain specific information. One way to combat this is to create indices for queries that are commonly performed. For instance, during off-peak hours, the server would search through the records to identify those that belong to patients with a particular syndrome, and store a list of those records in memory or as another encrypted BLOB. Users of the index would need to be made aware that the index was only valid up to the time of its creation.

Yet another further step in improving performance in a store with encrypted records is to split each individual record into multiple BLOBs (E.g. one BLOB per clinical category.) This model further increases performance while also further decreasing privacy since the mere existence of a BLOB in a particular category may be too revealing about the corresponding record.

The reference implementation of Indivo utilizes a data store that is an encrypted xml file store that follows the model of one file per user. That is, all of the records are stored as files that contain digitally encrypted xml records. Other types of data stores could include databases and LDAP compliant directories and meta-directories. All of the models described above can be implemented in any of these back-end stores. However there are other models specific to databases and directories that utilize the benefits of such systems. These benefits include pre-existing indices (for none encrypted data), optimized search, existing query languages, load-balancing, and automated backup and distribution of data.

The Data Model

The data model for a personally controlled health record in Indivo is designed to be as generic as possible and yet still be capable of representing a collection of specific types of medical documents. To this end, we have adopted a philosophy of wrapping externally defined documents in an XML structure that provides information about how to interpret the documents' contents. Therefore, a personally controlled record in Indivo is merely a collection of documents, each with meta-data that describes how that document is classified within the record, the type of document that it is, a brief description of the documents contents, and its creation and modification time.

The Indivo reference implementation has some pre-defined document types that will be used in the personally controlled records. Some of these documents are defined by the Indivo team, and others have been defined by others in collaboration with the HL7 Clinical Document Architecture committee. The Indivo team has currently defined a document that contains the record owner's authentication credentials and a document that contains information about the owner's actor attributes (such as roles, group membership, and proxy information). Document types that represent various clinical documents for emergency department visits, clinical reports, laboratory results, and medications have been developed by the Indivo team, HL7, and others.

Our motivation for this meta-data scheme is primarily that we won't be reliant on the incomplete, emerging standards, but will be able to store documents produced by them and maintain useful information for processing them. We will also maintain copies of the current versions of these document descriptions so that, in the event that they change, we will be more easily able to migrate the older versions of documents to the new standard.

Resources