Secure Social Security Numbers in 6 Simple Steps for Developers

According to SSA.gov, identity theft is one of the fastest-growing crimes in America. Because of their status and importance, Social Security Numbers (SSNs) are a rich prize for identity thieves. Therefore, as an application developer or system owner, you must protect SSNs in your backend and all the way through to your web or mobile application. 

Handling data as sensitive as SSNs presents unique engineering challenges. Storing them in a SQL database in plaintext, without robust security mechanisms, isn't just risky — it's a data breach waiting to happen. This is where Piiano Vault comes in, offering specialized yet simple protection for critical data such as personally identifiable information (PII).

In this tutorial, you will see how to protect SSNs in 15 minutes, without the need for any prior security knowledge, just using a simple CLI.

Introduction to Piiano Vault

Piiano Vault is a tool that offers a secure backend for your sensitive data and an API and CLI for securely accessing that protected data. It’s like a safebox where you can store all your important data (your customers’ crown jewels). It supports many security and privacy compliance features out-of-the-box and will save you years of development time.

Here are some of the benefits Piiano Vault offers:

• Data management: Piiano Vault supports a data model that helps you manage customer data in your backend application easily. With configurable and automatic data retention policies, data tagging, semantic data types, traceability, privacy compliance features – such as DSAR and RTBF – and many other features.
• Uncompromised data security: Piiano Vault does the heavy data security lifting for you, behind the scenes. It transparently handles encryption, key management and rotation, auditing, and access controls. It has an advanced tokenization engine and other features to address security risks.
• APIs: Vault exposes a simple yet powerful REST API and delivers SDKs for several programming languages to store, tokenize, and encrypt any type of sensitive data.
• Portability and deployment flexibility: Vault can be used to secure data before it’s stored in a database. Vault can be used anywhere: 
  - in existing architectures (serverless or not, in various cloud providers, etc.) 
  - as a container or binary
  - as a fully managed SaaS solution.‍
• Performance: Optimized for high throughput and low latency, Piiano Vault manages tens of thousands of requests per second.

In this tutorial, you explore the nuances of using Piiano Vault's SaaS variant for optimal SSN protection. If you're interested in other deployment strategies, there's more information in the installation guides on the Piiano Vault website.

1. Get your vault

To get started, sign up on the Piiano Vault SaaS website. You can register using your Google or GitHub identity or your email address. Once registered, you have a full working instance of Vault for 7 days. When you have signed up, you land on the management console for your vault.

2. Install the CLI

Vault exposes its functionality through a REST API. There are also SDKs for various languages and ORMs, and an OpenAPI specification document that you can use to generate SDKs for other languages.

These options are complimented by the pvault CLI, a convenient tool for accessing Vault from the command line. You use this tool in the tutorial. You can install it easily using brew on MacOS or Linux. The CLI installation guide describes other Installation options.

% brew install piiano/tap/pvault-cli

3. Set up the CLI

To use the CLI, you need your vault’s endpoint address and an API key. You obtained these from the management console.

In your terminal, run the following commands to save the endpoint and API key for use by the CLI:

% export PVAULT_ADDR=
% export PVAULT_AUTH_TOKEN=

It's worth noting that your vault is running in DEVMODE. In this mode, an admin user has full access to data to simplify experimenting with the product.
In production mode, by default, admin users can't access any data. A best practice is to assign individual users with separate API keys for each user who needs to access data and give each user only the privileges they need to perform their role. See the manage users and policies guide for more information.

You can now make sure everything is configured correctly by running:

% pvault status

Expect to see:

+------+---------+<br>
| data | control | <br>
+------+---------+ <br>
| pass | pass    | <br>
+------+---------+

If you don’t get a pass, check that your vault is running: it can take a few minutes to start. To see if your vault is running, check the status on the website (the state box should show ‘running’).

If you still don't get a pass, check that:

• The vault address is resolvable on your computer with nslookup or equivalent.
• Your firewall settings allow outgoing connections to port 8123.

4. Create a collection

Vault stores and organizes data in collections, which are similar to SQL database tables. 

One of the advantages of Vault over an SQL database solution is that it includes a range of semantic native data types for common PII and PCI data. (You can also add data types for less common PII data.) The data types enable Vault to decide how to work with data, such as determining sensitivity, permissions, data-masking, etc.

Each collection is defined using a predefined schema prototype. This prototype provides the basic properties for your collection to which you add properties for the data you want to store. Vault includes two of these prototypes, PERSONS and DATA.

To handle your SSNs, create a collection called customers based on the PERSONS prototype schema. You define the SSN with the SSN data type and make the property unique, so your collection can only contain one record with a particular SSN. To help identify the customer, include an email address. You now use the collection CLI command to create your collection.

% pvault collection add --collection-pvschema "
customers PERSONS (
   ssn SSN UNIQUE COMMENT 'Social security number',
   email EMAIL UNIQUE COMMENT 'Personal email address',
)"

To which you get a response like this:

INF Command completed successfully
INF To use the collection, you will need to pass `--collection customers` in subsequent commands or `export PVAULT_COLLECTION=customers`
customers PERSONS (
   email EMAIL UNIQUE COMMENT 'Personal email address',
   ssn SSN UNIQUE COMMENT 'Social security number'
);

5. Store your data

Now that you’ve defined the collection, you can store SSNs in Vault and ensure they're fully protected.

To add data to your collection use the object CLI command:

% pvault object add -c customers --fields '{"email": "jane@gmail.com", "ssn": "123-45-6789" "id": "ae8a6cec-3609-4e57-b8dc-3212aaac40ce"}'

To which you get a response like this:

+--------------------------------------+
| id |
+--------------------------------------+
| ae8a6cec-3609-4e57-b8dc-3212aaac40ce |
+--------------------------------------+
Displaying 1 result.

Your data is now fully secure and automatically encrypted by Vault, but it’s transparent to you. The data is locked in the vault, and can be accessed only when allowed.

You can now fetch the data using the object CLI command:

% pvault object get -c customers -i ae8a6cec-3609-4e57-b8dc-3212aaac40ce 
--props id,email,ssn

To which you get a response like this:

Displaying 1 result. 
+--------------------------------------+----------------+-------------+ 
|   id   |   email   |   ssn   |
+--------------------------------------+----------------+-------------+ 
| ae8a6cec-3609-4e57-b8dc-3212aaac40ce | jane@gmail.com | 123-45-6789 | 
+--------------------------------------+----------------+-------------+

6. Mitigate SSN exposure

With Vault securely storing your SSNs, your next step is to ensure that the right people get the right access to it: you don't necessarily want everyone seeing the full SSN when they retrieve a record.

This is where two Vault features come into play: semantic data type masking and granular access controls.

Semantic data type masking can automatically apply a mask to data of a particular type simply by appending .mask to a property name as part of the data request.

However, that mask is only useful if the user requesting data uses it. This is where granular access controls policies come in. These policies help you ensure data is accessed in a least-privilege manner. For example, you may have a system where users need to be aware of the presence of an SSN but must not be able to read it. You set up an access control policy that only allows the system to read ssn.mask.

With appropriate access control set up, if the user requests a full SSN, they will get an error. However, they can read the data using the mask, like this:

% pvault object get -c customers -i ae8a6cec-3609-4e57-b8dc-3212aaac40ce 
--props email.mask,ssn.mask

To which they get a response like this:

Displaying 1 result. 
+----------------+-------------+
|   email.mask   |   ssn.mask  |
+----------------+-------------+
| j***@gmail.com | ***-**-6789 |
+----------------+-------------+

With highly sensitive data, such as social security numbers, users expect to see them masked with **** in a browser or mobile application. With Vault, you can ensure that the data is masked all the way from the source system to the end-point.

Security tip

Fetching masked data from Vault by default is one of the best things you can do to prevent data, such as SSNs, from being stolen from the (web-app) server. Allowing a web application to get only the masked version of the SSN (e.g., the last 4 digits only) reduces exposure. Even if the server is compromised, an attacker can’t change the security policies enforcing data-masking read operations on the property. In other words, if the attacker can steal any data, all they can steal is the masked version.

7. Monitor data access

Another advantage of Vault is its full audit log that records all operations and data access. The logged details include the object IDs, user and role of the client, properties accessed, and access reason. Of course, these logs don't include the data itself, as it is sensitive. These logs help you understand data access behavior and can be used for continuous monitoring and post-mortem analysis should any issues arise.

The following is an example of a log record of a data read:

{
  "id":
"AgAAAYs6lPF4Vu8qxAAAAAAAAAAYAAAAAEFZczzaBEY0QUFEOTZEOWowWEpfWWdBQQAAACQAAAAAMDE4YjNhZWItNDU1YS00ODc2LWFmYjEtMWZkNTMzYWI5MMm5",
  "content": {
   "timestamp": "2023-10-16T22:22:01.592Z",
   "tags": [
    "env:demo",
    "vault_id:213599835155935232",
    "source:app",
    "datadog.submission_auth:private_api_key"
   ],
   "service": "pvault-server",
   "message": "/api/pvlt/1.0/data/collections/entities/objects/68aa36f4-99d3-43b2-9eb0-d4373987fa1c",
   "attributes": {
    "reason": "AccountManagement",
    "status_code": 200,
    "user_name": "VaultAdmin",
    "backing_store": "psql",
    "type": "audit",
    "data_accessed": [
     "id",
     "type",
     "value"
    ],
    "data_requested": [
     "id",
     "type",
     "value"
    ],
    "customer_identifier": "vault-saas/production/ay4b63pxx425",
    "context": {
     "options": [
      "unsafe"
     ]
    },
    "dev_mode": true,
    "operation_id": "get-object-by-id",
    "vault_id": "213599835155932232",
    "registration_uid": "email|64d555401b22b79efc63d444",
    "product": "vault",
    "trace_id": "51cc78b8-0da9-4234-951b-a36a216d0a76",
    "iam_signature": "...e12c2cef47e9f49c",
    "customer_env": "demo",
    "method": "GET",
    "level": "info",
    "collection": "entities",
    "version": "1.8.1.5817948877-g9a8f311",
    "url": "/api/pvlt/1.0/data/collections/entities/objects/68aa36f4-99d3-43b2-9eb0-d4373987fa1c?&reason=AccountManagement&options=unsafe",
    "worker_id": "231593361142501376",
    "role_name": "VaultAdmin",
    "saas": {
     "id": "ay4b63pdz425",
     "env": "production"
    },
    "service": "pvault-server",
    "http": {
     "url_details": {
      "path": "/api/pvlt/1.0/data/collections/entities/objects/68aa36f4-99d3-43b2-9eb0-d4373987fa1c",
      "queryString": {
       "reason": "AccountManagement",
       "options": "unsafe"
      }
     }
    },
    "personsIDs": [
     "68aa36f4-99d3-43b2-9eb0-d4373987fa1c"
    ],
    "time": 1697494870455,
    "deployment_mode": "container"
   }
  }
}