TrueVault is a platform that enables developers to build secure, compliant applications without being experts in security or compliance. It is designed from the ground up to provide HIPAA Compliant storage for Protected Health Information (PHI) and Personally Identifiable Information (PII), but the security features make it well suited for storing any sensitive data.

This introduction will take you through the high level functionality and API concepts, all the way down to concrete sample code. We strongly recommend taking a few minutes to read the entire guide in order, but if you know what you're looking for you can jump right in.

  1. Major TrueVault Features
  2. API Concepts
  3. Common Architecture
  4. Security & Compliance
  5. Quick Start
  6. Sample Code

Major Features

TrueVault combines three major pieces of functionality to offer a secure data store that enforces user access control end-to-end: from the UI all the way to the Database.

  • Secure Data Storage: Store your structured data as JSON and your unstructured data as raw binary.
  • Access Control: Set group-level policies that control access to your data stored in TrueVault.
  • User Management: Offload user identity management, login, and session management.

These core features work in tandem to offload as many security and compliance concerns as possible, allowing you to focus your energy on value add features for your customers.

API Concepts

To understand the API Documentation, it can be helpful to have a high-level understanding of the core constructs.

BLOBs

BLOBs are "Binary Large Objects", and within TrueVault represent your unstructured data. You can store any binary file you want, in any format (images, PDFs, DICOM, or any proprietary format). Create a BLOB for any binary data you need to encrypt and secure access to.

Documents

All of the structured data you store in TrueVault are called Documents. Documents are JSON formatted, but can have any structure you want. You can search across documents that have similar fields by associating them with a Schema.

Schemas

You can use TrueVault to search across a set of Documents, provided you associate them with a Schema. Schemas describe the structure of your data, specifying the types of the fields you intend to search by, enabling type-specific indexing. Schemas don't need to be a comprehensive description of all fields in your documents, but the types in your schema must match the corresponding types in the documents you create. Schemas live within a single Vault, but you can have multiple Schemas within one Vault.

Vaults

Documents and Blobs live inside a Vault. Within your account, you can have many Vaults. Vaults are an abstraction that allow you to organize similar data together, and express access control rules for these data using group policies.

Users

All API Calls made in TrueVault are tied to a User. Users can be used to represent two concepts:

  1. End Users
  2. System Users

End Users are your users. Each human that uses your application should map to a single user in TrueVault, so each authenticated API request can be uniquely tied to the person responsible (this is an important concept for complete Audit Logging). End Users can log in to your application with username, password, and MFA token using the TrueVault Login API. After successful login, TrueVault issues a User Access Token which can be used for authentication on subsequent requests. In normal use, End Users should never need to use an API Key.

System Users, on the other hand, generally do use API Keys instead of username/password and User Access Token. System users are background prcesses, or scheduled jobs which need to interact with TrueVault directly. Caution: we do not advise that you pull data out of TrueVault on an unsecured server. Even transient contact with PHI and PII requires a secure and compliant environment. Instead, you may use a system user to tell TrueVault you want to send an email to a specific user id. In this pattern, your server won't come into contact with the PII. Your server sends an opaque user id to TrueVault, along with the email message, and we add the email address.

Learn more about user registration, user login/logout, authentication basics, and user search.

Groups

Groups allow you to, well, group users together. A user can be in many groups, and a group can have many users in it. Groups also have Group Policies associated with them, which grant access to resources in TrueVault.

Group Policies

Group Policies allow you to specify fine-grained access to TrueVault resources, like Documents, BLOBs, and Users. We recommend that you create group policies that give users only the minimal access they require.

Learn more about implementing access control and access control best practices.

Common Architecture

TrueVault specializes in security and provides identity management, authentication, access control, and data storage. For some applications, TrueVault can serve as the entire backend. For many projects, there are features that are cumbersome or impossible to build efficiently on TrueVault alone, so a custom server environment is needed. Instead of investing in making the custom server completely HIPAA Compliant, we recommend you take an easier path: data de-identification.

In this architecture, you store all Personally Identifying Information in TrueVault. TrueVault gives you back an opaque identifier that you can store alongside your de-identified data in any server you chose. You can use any stack you want for your server-side code, and you can run that on your favorite infrastructure provider without any HIPAA concerns. You can re-identify this data in your client application when requested by an authenticated user. The system looks like this:

Architecture

Note that you shouldn't pass the PII through your server. If your server comes into contact with de-identified health data and the identifying data, even in passing, it falls under the purview of HIPAA. By splitting the data in the client application, you can easily stay compliant with much less effort.

Security & Compliance

Compliance

TrueVault is the fastest and easiest way to become HIPAA compliant, because the TrueVault service satisfies every technical and physical safeguard mandated by HIPAA. Compliant-hosting solutions are attractive because of they are easy to adopt, but they leave your team with a long list of responsibilities to become HIPAA Compliant, including comprehensive audit logging, access control enforcement, secure authentication, proper data encryption, key management, data recovery, and more.

TrueVault's unique approach ensures compliance by taking responsibility for user management, access control, and data storage through a single unified API. This makes it possible for TrueVault to ensure compliance for all the data you store with us. Below are some highlights that distinguish TrueVault's compliance offering.

Authentication

Everyone builds authentication for their products, but not everyone builds it correctly. Even large, respected software companies like LinkedIn and Yahoo have had substantial vulnerabilities in their authentication systems that have resulted in massive breaches. Authentication is your first line of defense against data loss, and an attacker's first target. TrueVault's secure authentication features not only save you time, but ensure you're compliant and secure.

Access Control

If you review as many HIPAA violation reports from the HHS as we do, you'll see that improperly implemented Access Control is one of the most common failures that cause breaches and hefty fines. Our Access Control is declarative and very specific, making regular reviews of access simple and easy. There's no back door to these rules, all requests for data through the TrueVault API are filtered through our battle-tested authorization logic. Using our access control not only speeds up your development, but it also decreases your risk profile dramatically.

Audit

Every user action and API call is logged by TrueVault. In the event of an audit, TrueVault will provide detailed logs showing which users performed which actions. Audit logs include specific actions (e.g. Create, Read, Delete) and specific resource identifiers (e.g. Blob Id, Document Id, Vault Id)

Important!

No Protected Health Information should pass, even intermittently, through a non-compliant server. If you plan on interacting with TrueVault from a server to exchange PHI, please ensure any hosting environment you use is completely HIPAA compliant. TrueVault has no way to ensure HIPAA compliance for data stored outside of TrueVault.

Security

SSL and HSTS

TrueVault forces HTTPS. We regularly audit the details of our implementation: the certificates we serve, the certificate authorities we use, and the ciphers we support. We use HSTS to ensure browsers interact with TrueVault only over HTTPS.

Encryption

All records are individual encrypted with AES using unique per-record 256bit encryption keys before they are stored. Decryption keys are stored in a separate, isolated key management cluster to restrict access.

Every protected record is encrypted with a unique initialization vector and a unique encryption key. Record integrity is enforced with a hash-based authentication code (HMAC) calculated using its own unique 256bit HMAC key. TrueVault verifies each record’s integrity on a scheduled basis and on each record request. Encryption keys, initialization vectors and HMAC keys are re-keyed on every update.

Quick Start

Now that you're familiar with the core concepts in TrueVault, take a few minutes to try the API for yourself. Follow the Quick Start Guide for inspiration on how to get started.

Sample Code

If you're looking for some concrete examples, you're in luck! We have several sample apps showcasing common functionality, and we're always looking for new ideas. Send us an email if you'd like to see something specific.

React JS Sample App

This is our largest Sample App by far, demonstrating the three-component architecture and data de-identification paradigm discussed above. The application is a collaborative diagnosis tool that demonstrates:

  • Supporting multiple user roles (administrator, doctor, and patient)
  • De-identifying data client-side
  • Creating Documents & BLOBs
  • End-User Authentication
  • System-User Authentication
  • TrueVault Email API

Check it out on GitHub.

User MFA Sample App

This application demonstrates how to implement the User MFA Endpoints in a simple JavaScript application. The application is small, and the functionality is limited to logging in and managing a ToDo list.

Read more about this app and watch a screen cast in our walk through.

Messaging iOS App

See the common private messaging use case demonstrated in Swift.

This app is coming soon! Email us if you'd like a sneak preview while we work on it.