Getting Started with InnoVault

With InnoVault, you secure and control the user’s Personally Identifiable Information (PII) for its entire data lifecycle. PII is encrypted for rest as soon as it’s produced and decrypted only when you need to process it. Processing PII is still extremely easy; just access it with our NoSQL object store. With end-to-end encryption, your systems and only your systems have access to the clear text data.

Very Quick Start

Preliminaries

  1. Create an account on the admin console. Use a good password.
  2. Save your account “paper key”. This is very important.
  3. After verifying your email, within the console, create a client key and a form with type pii.

Front End

We have a fancier JavaScript library, but let’s start with the simple one that automatically hooks into your form. Include our easy JavaScript library and annotate the fields you want to encrypt with “data-innovault-type” or download a complete one-page HTML example. 

<script type="text/javascript" src="https://js.innovault.io/1.0.2/innovault-easy.min.js"></script>
<form data-innovault-token="REPLACE_WITH_FORM_TOKEN_FROM_CONSOLE" method="post" action="https://yoursite.example/contact">
  <input type="text" name="fullname">
  <input type="text" data-innovault-type="dob">
  <input type="text" data-innovault-type="ssn">
  <button type="submit">Submit</button>
</form>

Now when your users submit data, these data elements will be end-to-end encrypted. Our web library gives you complete control over form submission, so read below for more information about that.

Back End (CLI)

For testing and basic reading and writing, you can use the E3DB command-line client. Save your secret client key in ~/.tozny/e3db.json, then when you’re ready to read records, you can run:

> e3db ls -jd -t pii

Back End (Ruby)

Of course, you probably want to handle your form data programmatically using one of the E3DB code libraries. Save your secret client key in ~/.tozny/e3db.json, install the SDK with ‘gem install e3db’ then when you’re ready to read records, you can run:

require 'e3db'
client = E3DB::Client.new(E3DB::Config.default)
client.query(type: 'pii').each do |record|
    puts 'Data:     ' + record.data[:dob] + ':' + record.data[:ssn]
    puts 'Metadata: ' + record.meta.record_id + ':' + record.meta.type
end

That’s (no where near) it!

Who knew end-to-end crypto could actually be easy! Read on for more information about our JavaScript SDK, command-line client, and libraries.

How it Works

The InnoVault Web SDK captures Personally Identifiable Information (PII) from HTML forms, encrypts that information in the browser, and stores it such that you can process that information without ever needing to store the PII anywhere but in the InnoVault database.

InnoVault stores PII in “Forms,” which is a location for storing PII data (submitted by an actual HTML form). You can sign up for InnoVault and create a Form using the Tozny Console.

InnoVault uses Tozny’s end-to-end encryption storage solution, E3DB, to store PII. With end-to-end encryption, your systems and only your systems have access to the clear text data. You can access the PII stored in a Form using one of Tozny’s E3DB clients. A command-line client is available, as well as SDKs for Ruby, Go, and Java.

Read on for details on creating and using InnoVault Forms.

Registering and Creating a Form

Registering: Start by going to https://console.tozny.com and registering for an account. There are free and paid plans available. Be sure to save your paper key in a safe place! Note that your password is used to encrypt certain data, so choose a good password.

Creating a Client: After verifying your email, go to the “Manage Clients” section and click “Add Client.” We recommend naming the client “Forms Client.”  This client will be associated with the Form created in the next step, allowing the PII submitted to be accessed via the E3DB CLI or one of our SDKs.

Then copy the JSON data from the text area to put in ~/.tozny/e3db.json, or you can download it later. Make sure you get the whole thing.

Creating a Form: Now go to “Manage Forms” and click “Add Form.”  Choose a name for the form and specify the type of records that will be stored. We recommend “First Form” and record type “pii.” Make sure to select the correct associated client, “Forms Client” for this example.

After the form has been created, click the “Retreive Token” button that appears next to the new form’s row. The token must be embedded in any HTML form that you want to store in InnoVault.

Copy the form token to your clipboard to paste into your front-end code, or retrieve it later:

Setting Up your Front-End Code

After creating a Form via the Tozny Console, you can choose between two different ways to use the form. The Easy SDK requires minimal HTML markup and no further programming. Our Web SDK allows front-end developers much more control over how the form is handled and processed, while still taking care of the complexities of cryptography.

In both cases, the SDK takes care of encrypting the PII, storing it in InnoVault, and giving you back a record_id, which is the globally unique handle that you can use to access data any time.

Collecting Encrypted PII with the InnoVault Client SDK

The Easy SDK works well if all or most of the form will be stored in InnoVault, and if the form is not dynamically generated by a JavaScript framework. For cases requiring custom processing or dynamic forms, the Web SDK should be used.

InnoVault Easy SDK variant

Using the Easy SDK requires three steps:

  • Import: Include the SDK’s source in your page using a <SCRIPT> tag:
    <script type="text/javascript" src="https://js.innovault.io/1.0.2/innovault-easy.min.js"></script>
  • Paste your Token: Add the data-innovault-token attribute to the <FORM> tag to indicate which form will store the PII. The value of the attribute should be the token displayed in the Tozny Console when you click “Retrieve Token” next to the Form in the “Manage Forms” section.
  • Mark the PII Fields: Replace the name attribute on each input field that holds PII with data-innovault-type. Only the attribute name needs to be replaced; the value (giving the name of the field) should remain.

For example, consider a form that collects Name, Date of Birth, and Social Security Number.

<form>
  <input type="text" name="fullname”>
  <input type="text" name="dob">
  <input type="text" name="ssn">
</form>

Assuming an InnoVault Form has been created in the Console already, we’d end up with this (encrypting DOB and SSN), or download a complete one-page HTML example.

<script type="text/javascript" src="https://js.innovault.io/1.0.2/innovault-easy.min.js"></script>
<form data-innovault-token="REPLACE_WITH_FORM_TOKEN_FROM_CONSOLE" method="post" action="https://yoursite.example/contact">
  <input type="text" name="fullname">
  <input type="text" data-innovault-type="dob">
  <input type="text" data-innovault-type="ssn">
  <button type="submit">Submit</button>
</form>

Form Submission Details

Converting an existing form to use InnoVault modifies the form submission process. The Easy SDK will collect, encrypt, and submit PII fields to InnoVault first. To support querying, the “data-innovault-type” fields and other metadata will not be encrypted. After storing the PII, the Easy SDK will insert two hidden input fields into the existing form, named “innovault_record_id” and “innovault_user_id”. The form will then submit as normal, except with PII removed.

Easy SDK Hooks

The Easy SDK provides several “hooks” that can be used to customize form submission. In particular, you can register a form dynamically, receive an event before the form is submitted, and receive an event after submission (which will include the record_id assigned to the encrypted PII). If you want to do anything fancier than this, read on for the web SDK variant that gives you more control.

  • registerForm(form, token) -- Use this method to register a form created after the page finishes loading. form must be a DOM element, while token must be the InnoVault Form token given by the Tozny Console.
  • beforeSubmit(formName, callback) -- Registers a function to be called before the given form submits. formName should be the value of the name attribute on the form element that you want to track.
  • afterSubmit(formName) -- Returns a Promise that can be used to process the results of submitting the form with a name attribute equal to the value of formName. The promise will call any then methods with an object containing a record_id field, which will be the unique ID associated with the encrypted PII.

InnoVault Web SDK Variant

The Web SDK provides the building blocks for storing PII in InnoVault, and gives you complete control over how that data is collected. In essence, the Web SDK will encrypt and store a JSON document in the Form location you specify.

The Web SDK can be installed via the Node Package Manager (NPM) or from Tozny’s CDN. To install via NPM, run:

npm install innovault-web-sdk

To load the SDK from Tozny’s CDN, check here:

https://js.innovault.io/1.0.2/innovault-web.min.js

Usage

The Web SDK provides one global variable, innovault.web.sdk, with one function, submit:

innovault.web.sdk.submit(token, form)

The form argument will be converted to JSON, encrypted and stored in the Form indicated by the token argument. form must be an object. Keys will be stored as plain text (not encrypted). Values must be strings (for consistency, we recommend using JSON.stringify on all values before submitting.)

The value of token should be the token obtained from the Tozny Console when the form was created.

submit returns a Promise object which can be used for further processing after the SDK has submitted the form value to InnoVault. The Promise will “return” an object containing a record_id field that indicates the ID associated with the encrypted record.

The record_id value can be used to retrieve the record later with an E3DB client, and should be used to associate PII in an InnoVault Form with non-PII stored elsewhere. Here’s an example in action or download a complete one-page HTML example.

 <script type="text/javascript" src="https://js.innovault.io/1.0.2/innovault-web.min.js"></script>
 var token = "REPLACE_WITH_FORM_TOKEN_FROM_CONSOLE"
 var form = {
 fullName: "Jon Snow",
 dob: "1-1-1981",
 ssn: "123-45-6789"
 };
 
 innovault.web.sdk.submit(token, form)
 .then(function (data) {
 console.log(data); // { "record_id": "...", "user_id": "..." }
 });

Setting Up your Back-End Code

Processing PII

PII collected into InnoVault can be processed using an E3DB Client. Our clients make it easy to transparently handle encrypted data.

Tozny provides a command-line client (CLI) with binaries for Windows, Linux, and MacOS. We also provide SDKs in Go, Ruby, and Java that can be used to write a custom client. Here, we will discuss accessing PII using the CLI and the Ruby SDK.

Downloading Secret Client Information

Every Form is associated with an E3DB client. To access the PII stored by the Form, you need to download the associated client’s secret key and credentials. The following three steps will allow you to access the PII associated with a given form:

  1. In the Tozny Console, go to the “Manage Forms” section and make a note of the client associated with the form.
  2. Go to “Manage Clients” and click the “Retrieve Key” link next to the client identified in the previous step. This is your secret client key.
  3. Copy the JSON data from the text area and save it in ~/.tozny/e3db.json or “~/.tozny/profileName/e3db.json” if you have multiple client keys on the same machine.
The JSON object representing your client configuration looks like this (~/.tozny/e3db.json):
{
	"version": 1,
	"api_url": "https://api.e3db.com",
	"api_key_id": "3daf9ad3-c677-4004-b690-cfd689bb0c03",
	"api_secret": "9274da84-6ca0-4516-a7dc-da7ee2a178db",
	"client_id": "bd71c057-e7e9-4015-80a6-b0f9e00fbd2c",
	"client_email": "example@tozny.com",
	"public_key": "97eac3f9-7864-4410-bad0-c1f15b4d683e",
	"private_key": "105318cf-fa51-460d-92f3-c82ef4fc425f"
}

Using the E3DB Command-Line Interface (CLI)

The E3DB CLI can be used read any PII written to your Form after you’ve downloaded the appropriate credentials as described above. Download the CLI on our downloads page.

  • Windows -- e3db-windows-386.
  • MacOS -- e3db-darwin-386.
  • Linux -- e3db-linux-386

To run the executable, open a terminal (or command prompt) and execute the program. See below for example commands.

Accessing & Decrypting Data

The CLI’s ls command can be used to list all records uploaded by your HTML form to your InnoVault Form client. To see a list of record IDs, execute:

> e3db ls
f1ff8856-a0da-4e34-a9d6-6ea23f3df161     pii
4d4e9dfc-f1dd-4e0d-865a-f6441a2a8e74     pii
...

To see just records of type pii, run:

> e3db ls -t pii

To see the actual data submitted, add the -jd flags:

> e3db ls -jd -t pii
[
  {
    "meta": {
      "record_id": "...",
      "writer_id": "...",
      "user_id": "...",
      "type": "pii",
      "plain": {
...
      },
      "created": "...",
      "last_modified": "...",
      "version": "..."
    },
    "data": {
      "dob": "...",
      "ssn": "..."
    }
  },
 ...

The data element contains all the PII submitted to the form. The type is “pii” as configured when you created the form in the admin console.

Using the E3DB Ruby SDK

Download the client key (configuration file) as described above if you haven’t already. The Ruby SDK is set up to read the client key from ~/.tozny/e3db.json by default. The following code example prints out all of the records of type “pii” (as configured when you created your form in the admin console).

require 'e3db'
client = E3DB::Client.new(E3DB::Config.default)
client.query(type: 'pii').each do |record|
    puts 'Data:     ' + record.data[:dob] + ':' + record.data[:ssn]
    puts 'Metadata: ' + record.meta.record_id + ':' + record.meta.type
end

The output from this script would be something like:

Data:     1/1/81:111-111-1111
Metadata: dacbbd52-901c-45f7-93c8-674b189c54f9:pii

Remember that user data input from forms is untrusted, so handle it as appropriate. We recommend you use a different client or a different datatype for trusted data. For instance, after validating your data, you could rewrite the it (also end-to-end encrypted) with a new data type:

client.write('pii-trusted', {:dob => "1/1/81", :ssn => "111-111-1111"})

For more detailed examples of reading, writing, and querying data from the Ruby client, follow the example found on our Github repo. For information about using our other clients, see the documentation page.

A Few Words on Script Security

While Tozny strives to keep our infrastructure secure and will only ever distribute script files over encrypted (HTTPS) connections, that’s sometimes not enough to ensure end-user confidence in the integrity of those scripts. In order to help better protect your users from potential attacks against our infrastructure, Tozny publishes the SHA hashes of each script to allow your site to properly implement Subresource Integrity (SRI).

When adding an InnoVault script to your own site, you can add the SHA hash of the script and an “anonymous” cross-origin flag to the include. When your user’s browser downloads the script, it will verify the downloaded file’s hash against the hard-coded value; if the script has been modified in any way it will not execute.

The SRI version of the script include for the InnoVault Easy SDK variant is:

<script type="text/javascript" src="https://js.innovault.io/1.0.2/innovault-easy.min.js" integrity="sha384-0RHUIWE2AUtHboknEpzdRU6jIMuxKEOmGcgnZyhQsRmwTnVYttQFhldp6Be9chFD" crossorigin="anonymous"></script>

The SRI version of the script include for the InnoVault Web SDK variant is:

<script type="text/javascript" src="https://js.innovault.io/1.0.2/innovault-web.min.js" integrity="sha384-7Fnanu/5+Mu87uh9hZfwbp00SSCA8y5u1F/DUQe2u9wrrCxTVI/aaCAD5qS68RKE" crossorigin="anonymous"></script>

A Few Words on Crypto

Although InnoVault is very easy to use, behind the scenes it’s using strong cryptography, so a few words of caution are in order.

How to Lose Data: Whenever you encrypt something, you need a key to decrypt it, and so there is always a chance of losing data if you lose your keys. We do our best to mitigate that, but it is still possible for you to lose data. Tozny does not have access to your data or your keys, so we cannot recover your data if you:

  • Lose your client key (“Forms Client” in the example above),
  • Forget your password to the admin console, and
  • Lose your paper key

How account recovery works: Your client keys are backed up and encrypted with an account key that’s based on your password so you can retrieve them from the admin console. If you lose your password and reset your account via your paper key, your clients will also be restored. You can also recover your account via email, but you will lose your client keys if you do so.

How the Crypto Works: InnoVault is implemented using Tozny’s end-to-end encrypted database, E3DB. Your systems and only your systems have access to the plain text. An E3DB client is generated in the browser. Each field is encrypted with a unique “data key” and the data keys are encrypted with an “access key”. The access key is then encrypted with your client’s public key so that the client can download and access it later. The “names” of the fields are not encrypted, in order to support querying. We may add encrypted names soon. Let us know if this is of interest. Read more about our cyrpto.

A Few Words on Backups and Redundancy

In order to ensure the long-term availability of your data, we use best practices for backups and service redundancy using Amazon Web Service (AWS) tools. We’re constantly evolving and improving these processes so you can be confident that your data is safe with us.

We perform nightly and weekly snapshots of all data so we can restore in the event of a failure on the AWS side of things. We have database failover configured between Amazon’s availability zones. We write to a primary zone, and data is mirrored to the other zones. If the primary database were to ever go down, we fall back to the redundant ones automatically.

For API availability, we have servers running in all three availability zones in AWS’ us-west-2 region (Oregon) with round robin load balancing between them. If one server fails, the AWS Elastic Load Balancer (ELB) will automatically move traffic to the other 2 redundant servers, giving the system time to restore the failed machine. We’re using TCP load balancing at the ELB level, meaning the raw packets are forwarded into our stack without touching the TLS encryption. We don’t do TLS termination until inside our infrastructure. All communication inside our infrastructure is encrypted with IPsec.

Known Limitations

  • In order to use the following form types, use the web SDK, not the easy SDK so that you can determine what serialization you want. The easy SDK will not automatically process these form elements, and will throw an error if it encounters them:
    • File, image, submit, reset, button
    • radio
    • checkboxes
    • select (single & multiple)
    • The JSON data submitted is expected to be Strings for keys and values.
  • Re-sharing records:
    • Records written by InnoVault Forms cannot be shared with other clients without processing / rewriting them first. This currently enforced by our policy language because those records should be considered untrusted data. In order to share them with multiple clients, rewrite them (e.g. to a different type) first.

There’s Always More

There are a lot more concepts, features, and possibilities than we can cover in this short tutorial. Read this brief primer for information about InnoVault and E3DB. Watch our blog and Twitter for more announcements and new features coming soon!

Finally, please send us feedback any time.

Thank You!

  • The Tozny Team