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:
Step 2: Install Vault locally
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.9.5
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
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.
To install
pvault
CLI for macOS, run:brew install piiano/tap/pvault-cli
To run as a stand-alone binary, download the
pvault
CLI for your platform and extract the archive.To run the
pvault
CLI as a container and to make working with it easier, create an alias for it topvault
:alias pvault="docker run --rm -i --add-host='host.docker.internal:host-gateway' -v $(pwd):/pwd -w /pwd piiano/pvault-cli:1.9.5"
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 |
+--------------------------------------+
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 token
To delete a token:
pvault token delete --collection customers --token-id $TOKEN
Which returns:
INF Command completed successfully
Delete data
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
- 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.