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: 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 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.6.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 --add-host='host.docker.internal:host-gateway' -v $(pwd):/pwd -w /pwd piiano/pvault-cli:1.6.0"
⚠️ Docker Desktop displays a warning when mapping the home directory to a container.
It is thus recommended to run this command from a different directory or alternatively replace the $(pwd)
in the alias above with the desired 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 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')
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 | +1121212123 | 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 | +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 $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:
INF Command completed successfully
To delete an item from a collection:
pvault object delete --id $ID --collection customers
Which returns:
INF Command completed successfully
Next steps
- Check out more guides to get up and running.
- Review the API reference and CLI reference to discover more commands.
- Learn how to configure your deployment or manage users and policies.