IPEHR

Disclaimer

The project is under active development and will gradually be supplemented.

Description

Today common HMS applications store patients’ data in a local or a cloud DB which creates significant security, reliability and operational risks. Centralized storage and access rights administration of sensitive medical data create additional challenges:

Administrative overhead due to the rights provisioning on per patients/per record level.
Patients lack control and visibility over who has access to their data which goes against natural data subject rights announced in GDPR (General Data Protection Regulation, chapter 3).
Superuser access for DB and LDAP (access rights catalogue) create additional security risks.
In case of a data breach full registry will be compromised.

The IPEHR (InterPlanetary EHR) project is held to propose an alternative way of storing the data registry. Patients’ data will be stored in Filecoin network and will be accessed directly by stakeholders in case they have proper rights. Access rights and documents’ indexes will be stored on a blockchain in a smart-contract. Every data subject will have full unalienable control over his data and manage access rights on a personal level.

Watch video introduction:

Key features of the IPEHR solution:

all data is stored in a decentralized storage;
data encryption;
self-management of user’s access rights;
data integrity and authenticity is guaranteed by a smart contract.

Development roadmap

This work is being done under the FileCoin development grant program RFP. See our proposal here

The solution is being developed with 7 milestones:

Development of MH-ORM and structure of storage of medical data - completed
The functionality of encryption and saving/reading personal data to/from Filecoin - completed
Access rights management on a blockchain - completed
BsnGateway. Implementation of OpenEHR API, integration with MH-ORM - completed
Public data publishing features using the Chainlink network - completed
Application to manage your own medical data and access - completed
Testing, documentation and deployment - delivery

Milestone 1

On Milestone 1 we've developed the IPEHR-gateway to provide benefits of decentralized architecture to common HMS solutions using standard APIs.

IPEHR-gateway features:

generates user’s cryptographic keys;
exchanges medical data with HMS in openEHR format;
provides filtering and search functions by indexing received openEHR documents;
encrypts openEHR docs and indexes;
stores encrypted openEHR documents in the FileCoin decentralized network;
stores encrypted documents’ indexes in a smart contract on a blockchain;
sends decrypted documents back to HMS;
supports AQL queries without decrypting data.

Milestone 2

On Milestone 2 we have developed indexes storage, access revocation algorithm and integrated the IPEHR-gateway with the Filecoin network.

The main functions of a smart contract are

Search for ehr_id by user ID
Obtaining a list of documents related to the specified ehr_id.
Getting meta-information of the document by ehr_id and document_uid.
Getting an access key to the document.
Management of access to the document.
Document search using AQL queries.

User and EHR document data in the contract is stored encrypted and prevents unauthorized persons from accessing private information.

For more information see here.

Access rights management

To grant access to a document, the document access key is asymmetrically encrypted with the public key of the user (or group) being granted access and added to the IPEHR smart contract table.

For more information see here.

Milestone 3

From the point of view of a smart contract, a document is a structure that contains a certain set of attributes:

struct DocumentMeta {
    Status      status;
    bytes       id;
    bytes       version;
    uint32      timestamp;
    isLast      bool;
    Attribute[] attrs; 
}

At this point we will distinguish three levels of access: Owner, Admin, Read

Access to documents is managed according to the following access matrix:

Who \ Whom	Owner	Admin	Read
Owner	no	grant restrict	grant restrict
Admin	no	grant	grant restrict
Read	no	no	no

List of methods:

userGroupCreate - Creates a group of users
groupAddUser - Adds a user to a group
groupRemoveUser - Removes a user from a group
docGroupCreate - Creates a group of documents
docGroupAddDoc - Add a document to a group
docGroupGetDocs - Get a list of documents included in the group
setDocAccess - Sets the level of user access to the specified document
getUserAccessList - Get a list of documents to which the user has access

For more information see Milestone 3 repository

Milestone 4

AQL queries are used to search and filter data.

Archetype Query Language (AQL) is a declarative query language developed specifically for expressing queries used for searching and retrieving the clinical data found in archetype-based EHRs.

When new EHR documents are created, the homomorphically encrypted data they contain is placed in a special DataSearch index tree structure located in a blockchain. Indexes are searched using a smart contract. Later selections can be made from this data using AQL queries.

You can find a detailed description of the AQL specification on the openEHR website: https://specifications.openehr.org/releases/QUERY/latest/AQL.html

Client applications use AQL data queries, this way platform can be used by the 3rd party applications supporting the standard.

In the process of implementing the ability to execute AQL queries, the following tasks were performed:

Index data repository developed: https://github.com/bsn-si/IPEHR-gateway/tree/develop/src/pkg/storage/treeindex
Smart contract for storing index data: https://github.com/bsn-si/IPEHR-blockchain-indexes/blob/develop/contracts/DataStore.sol
AQL querier(*) - library for parsing an AQL query: https://github.com/bsn-si/IPEHR-gateway/tree/develop/src/pkg/aqlprocessor
AQL executor(*) - service that searches the index tree for data according to an AQL query: https://github.com/bsn-si/IPEHR-stat/tree/main/internal/aqlquerier

On receipt of a request, the IPEHR gateway interprets the request into a set of conditions, which is used to search the DataSearch index structure and returns the result to the requestor as specific values or as links to documents containing the requested data.

For more information see Milestone 4 repository

Milestone 5

On Milestone 5 we've developed a service that pushes public statistical data collected by the ipEHR system from stored EHRs to Chainlink network. The service implements an open API with specified metrics. The data is collected and processed by IPEHR-blockchain-indexes smart contracts.

EHR stats can be collected by the service through:

transaction analysis of contracts IPEHR-blockchain-indexes
periodic direct invocation of contract methods IPEHR-blockchain-indexes
making AQL queries to IPEHR-gateway

We have implemented two types of statistical data delivery:

Direct delivery. Is implemented as a task in Chainlink that receives requests from outside by listening to the Oracle contract. When the Consumer contract sends a request for the statistical data to Oracle, the job collects a small fee in Chainlink tokens and returns the result from the statistics server. For this case, we have an open API for statistics and documented schema of job for Chainlink. The contract for this request is not a library but a sample contract in which we request statistical data via Oracle from the certain job of Chainlink
Scheduled delivery. It consists of two contracts and the schema of a Chainlink job. This job automatically requests statistical data within the specified interval and sends it to a storage contract. All other external contracts can request statistical data from the storage contract. The implementation includes two contracts. The first is the storage itself. We publish it and pay for its updates. The second is the contract of a Consumer. It is a sample of a simple contract that requests statistical data from storage.

For more information see Milestone 5 repository

Milestone 6

We've developed an application (mobile/web) helping users to manage their personal data and its’ access rights. To control access to EHR Documents the following smart contracts are used: EhrIndexer, Users, AccessStore

For each Patient during registration, a group of documents All documents and a group of users Doctors are created.

All new documents of the Patient are assigned to the group All documents.
All members of the Doctors group have access to the documents assigned to the `All documents' group.
The Patient can add Doctors to the Doctors group and they automatically get access to all Patient's Documents.
When a Doctor is removed from the 'Doctors' group, their access to document keys is terminated.

To read more info about access rights management, please visit the "docs access management" section.

To ensure the quality of the application we developed and showed a test case:

Milestone 7

Final throughput metrics of the ipEHR smart contracts:

Metric	Calibration	Sepolia
block_time	30 sec	12 sec
iterations	100	100
threads	20	20
time_total	39m14s	23m53s
http_reqs	4180	3545
iteration_time	14m13s	6m37s
user_register_time	2m20s	3m57s
user_login_time	112ms	139ms
ehr_create_time	4m14s	3m34s
ehr_get_time	119ms	107ms
user_logout_time	124ms	130ms
user_create_gas_used	258304636	943537
ehr_create_gas_used	1094164389	3168824

We have integrated the ipEHR gateway with the Better Studio HMS playground to pass EHR documents from the HMS to the FIL network. Here is the demonstration video:

For integration of the ipEHR gateway with the Better Studio HMS SandBox we have developed an ipEHR browser extension, you can download it here

Here's also a short demo video how to set the extension:

IPEHR-gateway installation

Clone this repo

cd /srv
git clone https://github.com/bsn-si/IPEHR-gateway

Docker

You can use the automatic building of components in Docker containers.
To do this, you will need Docker Compose installed. Installation instructions can be found here

cd /srv/IPEHR-gateway
docker compose up -d

After starting the service will be available at the address http://localhost:8080
You can interact with the service through the Swagger UI: http://localhost:8080/swagger/index.html

The containers can be stopped when the work is finished.

docker compose -f "docker-compose.yml" down

Building from source code

Install Prerequisites

Go

Please follow installation instructions provided here.

Build IPEHR-gateway

cd IPEHR-gateway/src
go build -o ../bin/ipehr-gateway cmd/ipehrgw/main.go

Config IPEHR-gateway

cd /srv/IPEHR-gateway
cp config.json.example config.json

You can change the parameters inside the configuration file according to your needs.

To work, you will need a private account key in the blockchain, which will be used to send transactions. By default it is located in the file $HOME/.ipehr/.blockchain.key, but you can specify another path in the config in the contract.privKeyPath parameter.

mkdir -p ~/.ipehr
echo "ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" > ~/.ipehr/.blockchain.key
chmod 600 ~/.ipehr/.blockchain.key

In order for an account to be able to interact with contracts, it must be added by the contract administrator to the whitelist.

Run IPEHR-gateway

cd /srv/IPEHR-gateway
./bin/ipehr-gateway -config=config.json

After starting the service will be available at the address specified in the configuration file. By default: http://localhost:8080
You can interact with the service through the Swagger UI: http://localhost:8080/swagger/index.html

IPFS

The ipEHR gateway requires a connection to the IPFS network. You can use a third-party service or install your own node. Installation instructions can be found here.

Filecoin node installation

The ipEHR gateway requires a connection to the Filecoin network.
It is necessary to install your own Lotus instance.
You can use an instance deployed by the IPEHR development team http://lotus.dev.bsn.si/rpc/v1 or deploy your own.
You can run it in either full node mode or light mode. Installation instructions can be found here.

Enable support for fetching data from IPFS before launching in the config ~/.lotus/config.toml

[Client]
UseIpfs = true

Creating a directory to retrieve files and then transfer them to the IPEHR-gateway

mkdir -p $LOTUS_DIR/files

Install Nginx to retrieve files on the IPEHR-gateway.

/etc/nginx/conf.d/lotus.conf:

server {
        server_name <HOSTNAME>;

        location /files {
                alias <LOTUS_DIR/files;
                add_header Content-disposition "attachment; filename=$1";
                default_type application/octet-stream;
        }

        location / {
                proxy_pass      http://127.0.0.1:1234;
        }
}

Replace <HOSTNAME> and <LOTUS_DIR> with your values.

Running tests

cd /srv/IPEHR-gateway/src
go test -v ./...

Get swagger UI API documentation

Swagger UI API docs

The following methods are based on the standard specification of OpenEHR

Workflow example

You can use this instruction and try to create, update or get EHR For now we have the following methods:

Register a user
Log in under the or log out
Refresh JWT token
Create an EHR (also with exact id or different parameters)
Getting info on created summary EHR by subject id
Getting info on created summary EHR by summary id
Getting info on created EHR status
Getting info on EHR status version by time
Getting info on EHR by request id
Update EHR status with id
Create composition
Get composition
Update composition
Delete composition
Create group access
Get group access
Execute AQL request
Get a document access list
Set user access to the document

Project Documentation

You can find the project documentation here

Related repositories

A mobile app for access management to user's (patient's) EHRs.
A Chainlink publisher for public EHR stats.
An ipEHR smart contract for access management, indexes storage and obtaining EHR stats.

bsn-si / IPEHR-gateway