Skip to main content

Get started

Learn the basics of Piiano Vault.

This quick start guide gives you a hands-on introduction to the fundamentals of Piiano Vault.

Interactive lab

This guide includes a free interactive lab with a pre-configured Piiano Vault instance to experiment with.

Start interactive lab

Step 1: Install Piiano Vault locally

Running Piiano Vault locally is the easiest way to get started. This installation is not suitable for production use.

Prerequisites

To install Piiano Vault locally, you need:

  • A computer running macOS, Linux, or Windows
  • Docker

Install Piiano Vault

  1. Register for a free 30-days license to activate Vault.
  2. Pull and start the Piiano Vault server container, listening on the default Piiano Vault port of 8123:
    docker run --rm \
    --name pvault-dev \
    -p 8123:8123 \
    -e PVAULT_DEVMODE=true \
    -e PVAULT_SERVICE_LICENSE={LICENSE_KEY} \
    -d \
    piiano/pvault-dev:1.0.0

When the Docker container starts, you have a running Piiano Vault. You can access Piiano Vault on http://localhost:8123 and interact with it using the Piiano Vault API or the Piiano CLI. The local API reference (hosted here) allows you to experiment with the APIs directly from the browser.

Step 2: Connecting using the Piiano CLI

The Piiano CLI is a built-in command-line tool to interact with Piiano Vault. The Piiano Vault server includes an up-to-date installation of the Piiano Vault CLI, but the CLI is also provided on a dedicated container image. To make working with the CLI pvault command easier, create an alias for it:

alias pvault="docker run --rm -i -v $(pwd):/pwd -w /pwd piiano/pvault-cli:1.0.0"

You can now check the status of your Piiano Vault container to make sure it's running correctly:

pvault status

You should get this response:

+------+---------+
| DATA | CONTROL |
+------+---------+
| pass | pass |
+------+---------+

Step 3: Create a collection

Now you add a collection to Vault. You create a personal information aware collection like this:

pvault collection add --collection-pvschema "
customers PERSONS (
ssn SSN UNIQUE COMMENT 'Social security number',
email EMAIL,
phone_number PHONE_NUMBER NULL,
zip_code_us ZIP_CODE_US NULL,
)"

You should get a response similar to this:

customers PERSONS (
email EMAIL,
phone_number PHONE_NUMBER NULL,
ssn SSN UNIQUE COMMENT 'Social security number',
zip_code_us ZIP_CODE_US NULL
);

Step 4: Add data

Now add some data:

pvault object add --fields '{ "ssn":"123-12-1234", "email":"john@somemail.com", "phone_number":"+1-121212123", "zip_code_us":"12345" }' --collection customers
pvault object add --fields '{ "ssn":"123-12-1235", "email":"mary@somemail.com", "phone_number":"+1-121212124", "zip_code_us":"12345" }' --collection customers
pvault object add --fields '{ "ssn":"123-12-1236", "email":"eric@somemail.com", "phone_number":"+1-121212125", "zip_code_us":"12345" }' --collection customers

As you add each person, you should get a response similar to this:

+--------------------------------------+
| _id |
+--------------------------------------+
| b2ce6582-8ce0-4504-8008-886eeaaec978 |
+--------------------------------------+

Now you can query the ID of the first person you created by email and save it in a variable so you can use it in the examples that follow:

ID=$(pvault object query --match email=john@somemail.com --collection customers --props _id --json | docker exec -i pvault-dev jq -r '.results[0]._id')
info

Add sensitive (encrypted) data

Data in Vault is encrypted at rest. Vault provides automatic key provisioning and rotation. Data is also protected with granular access control, and access is fully audited.

Step 5: Tokenize data

Vault supports many options for tokenization of personal data. This enables a token to be created for items of sensitive data. The token can then be transmitted and stored outside Vault so authorized users can look up the referenced value, while others only see the anonymized token value.

So, you tokenize an email address like this:

pvault token create --object-id $ID --props email --collection customers --tag token_tag --type pointer

Which returns the token:

+--------------------------------------+
| token_id |
+--------------------------------------+
| 7520e2f5-2eaf-4678-9c16-98f7ec5fd223 |
+--------------------------------------+

Now you can get the metadata for the token using object-id or tag and save it in a variable so you can use it in the examples that follow:

TOKEN=$(pvault token info --collection customers --object-id $ID --json | docker exec -i pvault-dev jq -r '.[0].token_id')

Authorized users can recover the email address by detokenizing like this:

pvault token detokenize --token-id $TOKEN --collection customers

Which returns:

+--------------------------------------+-------------------+
| token_id | email |
+--------------------------------------+-------------------+
| 7520e2f5-2eaf-4678-9c16-98f7ec5fd223 | john@somemail.com |
+--------------------------------------+-------------------+

Step 6: Query your data

You can perform two types of query. A plain query returns the data as stored in Vault, while a transformed query returns data after transformations have been applied. You can also combine plain and transformed content in a query.

Plain query

To query all persons:

pvault object list --all-unsafe --collection customers --page-size 1

Which returns:

Displaying 1 result.
There are 2 remaining objects.
Use --cursor=AY0eCzxDCmna4PtAB7iQK0o7DAgYeAQhAWq2nR466PfQ5wvqve449pZ9huGJUkfRvfq5aQ== to show more.
+--------------------------------------+-------------------+--------------+-------------+-------------+
| _id | email | phone_number | ssn | zip_code_us |
+--------------------------------------+-------------------+--------------+-------------+-------------+
| b2ce6582-8ce0-4504-8008-886eeaaec978 | john@somemail.com | +1-121212123 | 123-12-1234 | 12345 |
+--------------------------------------+-------------------+--------------+-------------+-------------+

To query the first person's SSN property:

pvault object get --id $ID --props ssn --collection customers

This returns:

Displaying 1 result.
+-------------+
| ssn |
+-------------+
| 123-12-1234 |
+-------------+

To query all properties of the first person:

pvault object get --id $ID --all-unsafe --collection customers

Which returns:

Displaying 1 result.
+--------------------------------------+-------------------+--------------+-------------+-------------+
| _id | email | phone_number | ssn | zip_code_us |
+--------------------------------------+-------------------+--------------+-------------+-------------+
| b2ce6582-8ce0-4504-8008-886eeaaec978 | john@somemail.com | +1-121212123 | 123-12-1234 | 12345 |
+--------------------------------------+-------------------+--------------+-------------+-------------+

Transformed query

Vault provides desensitization of personal information by applying masks with transformations. Vault includes several built-in transformations, and future versions will enable you to add your own. Each transformation can act on any data of the same type, for example, masking emails, phone numbers and SSN.

pvault object get --id $ID --props ssn.mask,email.mask,phone_number.mask --collection customers

This returns:

Displaying 1 result.
+-------------------+-------------------+-------------+
| email.mask | phone_number.mask | ssn.mask |
+-------------------+-------------------+-------------+
| j***@somemail.com | ********2123 | ***-**-1234 |
+-------------------+-------------------+-------------+

Step 7: Delete data

Delete data

Delete token

To delete a token:

pvault token delete --collection customers --token-id $TOKEN

Which returns:

Command completed successfully

To delete an item from a collection:

pvault object delete --id $ID --collection customers

Which returns:

Command completed successfully

Next steps