PureKit Quickstart

This quickstart will guide you through PureKit MariaDB Demo App - a simple web application that illustrates how Virgil PureKit can be used with MariaDB to store and share data in the most secure way. The Demo App is based on a use case of a hypothetical business scenario involving a patient, physician and laboratory, and shows how distinct roles within a customer's application can be defined and used to restrict ePHI access in a HIPAA-compliant manner.

Note that this quickstart uses MariaDB for storing user records and keys; you can use the code samples to set up PureKit with your own storage or you can go through the Setup PureKit guide if you want to use Virgil Cloud to store records and keys.

Before you begin

Before getting started with the Demo App, you need to:

git clone https://github.com/VirgilSecurity/virgil-mariadb-demo.git

Set up and run demo

  • Step #1. Launch Docker.
  • Step #2. Create configuration files. Copy env.template file and rename to a new env.config file in the server directory.
  • Step #3. Get Virgil PureKit credentials. Fill in the Virgil PureKit values inside of env.config file. The following environment variables must be defined to run the server:
Variable NameDescription
virgil_appIdYour Virgil Application ID. Can be found at Virgil Dashboard.
virgil_atYour Virgil Application Token. Can be found at Virgil Dashboard.
virgil_pkService public key of your PureKit application. Can be found in your PureKit application at Virgil Dashboard.
virgil_nmsYour PureKit Non-Rotatable Master Secret key.
virgil_buYour PureKit Backup public key.
virgil_skYour PureKit App Secret key.

To generate virgil_nms, virgil_bu and virgil_sk, install the Virgil CLI and then run the following command:

virgil purekit keygen all

Make sure to save the generated keys in a safe storage.

  • Step #4. To run the demo client use the following command:
docker-compose up

How it works

The Demo App consists of three cards (actors): Patient (Alice), Physician (Bob) and Lab.

At any moment you can restart the demo and check the database using the buttons in the top.

Actors

In the beginning of the demo flow, each actor the following:

Alice has:

  • her SSN, which she can share with Bob;
  • access to the 2 prescriptions, that Bob has provided;
  • 2 lab tests that she is waiting for.

Bob has:

  • his license number, which he can share with Alice;
  • 2 prescriptions that he wrote for Alice, and a button to add new prescriptions;
  • 2 lab tests that he is waiting for, and a button to add a new lab test.

Lab has:

  • 2 lab tests that Bob has created for Alice.

Usage

At the Patient card:

  • Click "share to Bob" to securely share the Alice's social security number with the Physician.
  • Also, you can review prescription, lab's results and its status.

At the Physician card:

  • Click "Add prescription" to create a new prescription for Alice. Alice will immediately get access to the prescription and will be able to see the notes.
  • Also, at the Physician card, click "Add lab test". This will create a new record in Alice's, Bob's and Lab's "Lab tests" section.

At the Lab card:

  • In the column "Results" click "Add" button to add a test result. After submitting it, the Physician will be able to see the result, but the Patient will only see "Access denied" message in the "Result" column.
  • To share the result with the Patient, at the Physician card click "Share". After that the Patient will be able to read the result herself.

View MariaDB records

Now, to see the results of your actions in the database:

  • Click "View MariaDB" in the top of the page. There, in the left field, scroll to the very bottom to see the PureKit-related tables.
  • Click on any table and "Execute" to see the data in that table.
  • Note that most of the data will be encrypted (results of the lab tests in lab_tests, Patient's SSN in patients, Physician's license number in physycians, notes in prescriptions, encrypted keys and etc.) and can only be decrypted by users who have the right keys to do so. Therefore, sensitive data cannot be accessed by unauthorized parties.

Next steps

Now that you've seen the PHE flow working with sample code, we'll explore in the next guides how you can build PHE into your existing applications: