Quick Start: Node.js

You’re Alice and you have sensitive data to protect. (Don’t we all?)

Let’s see the fastest way to protect it server-side with the Virtru SDK.

Prerequisites

  1. Node.js 12 or higher

1. Install the SDK

We recommend installing our node package locally. That way, different projects can experiment with different versions of the Virtru SDK. After installing, you can verify the version you’re using:

Note: These steps assume a *nix style command line, as available in macOS and linux

npm install [email protected]
node -e "console.log('Using virtru-sdk: ' + require('virtru-sdk').Version)"

2. Get an identity

So Alice, who should own your sensitive data? You, obviously!

Authenticate to associate your email address (e.g. [email protected]) with any data you protect. You cannot protect data without authenticating. If the Virtru Platform doesn’t know who’s protecting data, no one would be able to access it later (when they’re also asked to authenticate).

The fastest way to authenticate on the server side is with an appId token. You can generate one from the Virtru Dashboard. If you need help, see detailed steps.

For safekeeping, don’t hard code your appID anywhere. A more secure option is to store it in your local environment:

export VIRTRU_SDK_EMAIL=[paste from Virtru Dashboard]
export VIRTRU_SDK_APP_ID=[paste from Virtru Dashboard]

To protect your sensitive data, we’ll need a Virtru client. We’ll associate anything you encrypt with your email and appId. Let’s make sure your email and appId can create a valid Virtru client to make further SDK calls.

// Quick Start - Step 2 - Get an identity
const Virtru = require("virtru-sdk");

// Set the environment variables:
//   VIRTRU_SDK_APP_ID: AppId Token from https://secure.virtru.com/dashboard#/settings
//   VIRTRU_SDK_EMAIL: Email address used for https://secure.virtru.com/dashboard#/profile
// Please note, the identity used will be associated with any policies created.

function loadVirtruClient() {
  try {
    const email = process.env.VIRTRU_SDK_EMAIL;
    const appId = process.env.VIRTRU_SDK_APP_ID;
    if (!email || !appId) {
      console.error(
        "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_APP_ID"
      );
      return;
    }
    const client = new Virtru.Client({ email, appId });
    console.log("Ready to protect!");
    return client;
  } catch (error) {
    console.error(error);
    return;
  }
}

module.exports.client = loadVirtruClient();
node 02-identify.js

3. Ask for sensitive data

Now that we know who will own things, why don’t you enter your first piece of sensitive data? For simplicity’s sake, create a file named “sensitive.txt” with your sensitive data.

echo "sensitive data" > ./sensitive.txt

4. Protect the sensitive data

Next, decide your encryption options. For now, it’s the file containing your sensitive data. In the future, this could include who else should have access and under what conditions.

// Quick Start - Step 4 - Protect the Sensitive Data
const { Client, EncryptParamsBuilder } = require("virtru-sdk");

async function protectToFile(unprotectedFile) {
  //auth
  const email = process.env.VIRTRU_SDK_EMAIL;
  const appId = process.env.VIRTRU_SDK_APP_ID;
  if (!email || !appId) {
    throw "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_APP_ID";
  }
  const client = new Client({ email, appId });

  // prepare
  const protectedExt = ".tdf.html"; // HTML format
  const protectedFile = unprotectedFile + protectedExt;
  const encryptParams = new EncryptParamsBuilder()
    .withFileSource(unprotectedFile)
    .withDisplayFilename(unprotectedFile)
    .build();

  // protect & output
  const protectedStream = await client.encrypt(encryptParams);
  await protectedStream
    .toFile(protectedFile)
    .then(() => console.log(`Encrypted file ${protectedFile}`));
  return protectedStream;
}

if (require.main === module) {
  const unprotectedFile = "sensitive.txt";
  protectToFile(unprotectedFile)
    .catch(e => {
      console.error(e);
      process.exit(1);
    })
    .then(() => console.log(`Done`));
}

module.exports.protectToFile = protectToFile;

Then, invoke the code using:

node 04-protect.js

5. Access the sensitive data

Now, let’s say you need to see your sensitive data again. Authenticate as [email protected] again and you can decrypt the protected file.

// Quick Start - Step 5 - Access the Sensitive Data
const { Client, DecryptParamsBuilder } = require("virtru-sdk");

async function accessToFile(protectedFile, unprotectedFile) {
  //auth
  const email = process.env.VIRTRU_SDK_EMAIL;
  const appId = process.env.VIRTRU_SDK_APP_ID;
  if (!email || !appId) {
    throw "An environment variable is not set:\n- VIRTRU_SDK_EMAIL\n- VIRTRU_SDK_APP_ID";
  }
  const client = new Client({ email, appId });

  // prepare
  const decryptParams = new DecryptParamsBuilder()
    .withFileSource(protectedFile)
    .build();

  // access & output
  const plaintextStream = await client.decrypt(decryptParams);
  await plaintextStream
    .toFile(unprotectedFile)
    .then(() => console.log(`Decrypted file ${unprotectedFile}`));
  return plaintextStream;
}

if (require.main === module) {
  const protectedFile = "sensitive.txt.tdf.html";
  const unprotectedFile = "sensitive_decrypted.txt";

  accessToFile(protectedFile, unprotectedFile)
    .catch(e => {
      console.error(e);
      process.exit(1);
    })
    .then(() => console.log(`Done`));
}

module.exports.accessToFile = accessToFile;

The decrypted file should match your original one with the sensitive data:

node 05-access.js
diff sensitive.txt sensitive_decrypted.txt

6. Access the sensitive data anywhere

If you inspect the generated HTML file, you still won’t find your sensitive data. It stays protected. You can send that HTML file to another machine or anywhere you want. Only you will be able to access it. But how do you do that outside of this code?

We could build a whole set of functionality to authenticate, decrypt, and render files. Or we could use Virtru’s Secure Reader, which is built to do exactly that for thousands of security-conscious users every day. In fact, if you open that HTML file from the last step, it will redirect you to Secure Reader.

Secure Reader will ask you to authenticate. (You’re still Alice, aren’t you?)

Authenticating with Virtru Secure Reader

And if you authenticate with the same email address you used to create the HTML file, you should be able to view it in Secure Reader:

Decrypting with Virtru Secure Reader

Congrats Alice! Your sensitive data is safe wherever it goes.

Updated 5 months ago


Quick Start: Node.js


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.