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.

Step 1: Register for your 7-day development license​

You have two easy options to get a running copy of Vault: create a fully managed Vault instance in Piiano SaaS or install Vault locally.

Head to app.piiano.io to get started with a managed Vault instance. When you have your license and have created a vault, continue at step 3.

If you want to work locally, first, get your development license:

Register to get a free 7-day development license, no credit card required.

Step 2: Install Vault locally​

note

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 developer edition​
Pull and start the Piiano Vault server container, listening on the default Piiano Vault port of 8123:
docker run --rm --init -d \
  --name pvault-dev \
  -p 8123:8123 \
  -e PVAULT_SERVICE_LICENSE={LICENSE_KEY} \
  piiano/pvault-dev:1.8.3

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 3: Connecting using the Piiano CLI​

note

If you are using the hosted version of Vault, the SaaS console displays the URL for your installation. You need to either set this in the --addr flag of each call or set it to the local environment variable $PVAULT_ADDR.

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. The CLI is also provided on a dedicated container image or as a stand-alone binary.

  1. To install pvault CLI for macOS, run: 

    brew install piiano/tap/pvault-cli

  2. To run as a stand-alone binary, download the pvault CLI for your platform and extract the archive.

  3. To run the pvault CLI as a container and to make working with it easier, create an alias for it to pvault:

    alias pvault="docker run --rm -i --add-host='host.docker.internal:host-gateway' -v $(pwd):/pwd -w /pwd piiano/pvault-cli:1.8.3"
danger

Docker Desktop displays a warning when mapping the home directory to a container. Therefore, it is recommended that you run this command from a different directory or replace the $(pwd) in the alias above with the alternative local directory (e.g., /tmp).

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 4: 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 5: 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", "id": "2b917e1b-c891-458d-ae62-ee01af36bc1e" }' --collection customers
pvault object add --fields '{ "ssn":"123-12-1235", "email":"mary@somemail.com", "phone_number":"+1-121212124", "zip_code_us":"12345", "id": "48e26d47-e1d2-4f51-8fc1-c05a6aec41c0"}' --collection customers
pvault object add --fields '{ "ssn":"123-12-1236", "email":"eric@somemail.com", "phone_number":"+1-121212125", "zip_code_us":"12345", "id": "fc49e2ce-85e5-4e4d-ad36-1b3f27210199" }' --collection customers

💡 When adding objects without an ID, Vault will automatically generate a GUID for each one.

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

+--------------------------------------+
|                  id                  |
+--------------------------------------+
| 2b917e1b-c891-458d-ae62-ee01af36bc1e |
+--------------------------------------+
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 6: 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 2b917e1b-c891-458d-ae62-ee01af36bc1e --props email --collection customers --tag token_tag --type pointer

Which returns a token similar to this:

+--------------------------------------+
|               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 2b917e1b-c891-458d-ae62-ee01af36bc1e --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 (your token ID will be different):

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

Step 7: 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 |
+--------------------------------------+-------------------+--------------+-------------+-------------+
| 2b917e1b-c891-458d-ae62-ee01af36bc1e | john@somemail.com | +1121212123  | 123-12-1234 |   12345     |
+--------------------------------------+-------------------+--------------+-------------+-------------+

To query the first person's SSN property:

pvault object get --id 2b917e1b-c891-458d-ae62-ee01af36bc1e --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 2b917e1b-c891-458d-ae62-ee01af36bc1e --all-unsafe --collection customers

Which returns:

Displaying 1 result.
+--------------------------------------+-------------------+--------------+-------------+-------------+
|                  id                  |       email       | phone_number |     ssn     | zip_code_us |
+--------------------------------------+-------------------+--------------+-------------+-------------+
| 2b917e1b-c891-458d-ae62-ee01af36bc1e | john@somemail.com | +1121212123  | 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 2b917e1b-c891-458d-ae62-ee01af36bc1e --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 8: Delete data​

Delete data​

Delete token​

To delete a token:

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

Which returns:

INF Command completed successfully

To delete an item from a collection:

pvault object delete --id 2b917e1b-c891-458d-ae62-ee01af36bc1e --collection customers

Which returns:

INF Command completed successfully

Next steps​

On this page