Quick Start: Client-side JavaScript

You’re Alice and you have sensitive data to protect. (Don’t we all?) Let’s see the fastest way to protect it client-side with the Virtru JavaScript SDK:

Prerequisites

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

0. Run a basic server

Because the Virtru JavaScript SDK respects strong security practices like CORS, you’ll need to run a basic web server for your first app. Running JavaScript in a local HTML file will not work.

<html>
  <head>
    <title>Boilerplate - Virtru SDK for JavaScript - Sample Application</title>
    <script src="https://sdk.virtru.com/js/2.0.1/virtru-sdk.min.js"></script>
  </head>
  <body>
    <script type="text/javascript">
      alert("Virtru.Version: " + Virtru.Version);
    </script>
  </body>
</html>

Let’s use Parcel for packaging, which also provides a local web server with a self-signed HTTPS certificate for testing.

npm install -g parcel
parcel --https index.html

Open your browser of choice to https://localhost:1234, Parcel's default URL.

1. 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 is with Virtru’s auth widget.

<html>
  <head>
    <title>Auth - Virtru SDK for JavaScript - Sample Application</title>
    <link
      href="https://sdk.virtru.com/js/latest/auth-widget/index.css"
      rel="stylesheet"
    />
    <script src="https://sdk.virtru.com/js/latest/auth-widget/index.js"></script>
    <script src="https://sdk.virtru.com/js/2.0.1/virtru-sdk.min.js"></script>
  </head>
  <body>
    <div id="virtru-auth-widget-mount"></div>
    <script src="./main.js"></script>
  </body>
</html>
function afterAuth(email) {
  alert(`Hello, ${email}. You're ready to protect with Virtru!`);
}

// Set up Virtru auth widget
Virtru.AuthWidget("virtru-auth-widget-mount", { afterAuth });

2. 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, let’s use a quick string.

function afterAuth(email) {
  // Ask for sensitive data
  const yourString = prompt("Type something to encrypt: ", "sensitive data...");
}

// Set up Virtru auth widget
Virtru.AuthWidget("virtru-auth-widget-mount", { afterAuth });

3. Protect the sensitive data

To protect your sensitive data, we’ll need a Virtru client. We’ll associate anything you encrypt with your email (from the auth widget):

const client = new Virtru.Client({ email });

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

  const encryptParams = new Virtru.EncryptParamsBuilder()
    .withStringSource(plainText)
    .build();

Finally, since the encrypt call is asynchronous, we’ll wait for it to finish:

  const ciphertextStream = await client.encrypt(encryptParams);
  console.log(await ciphertextStream.toString());

How do we know it worked? We should see ciphertext when we examine what got returned from encrypt.

async function afterAuth(email) {
  // Ask for sensitive data
  const plainText = prompt("Type something to encrypt: ", "sensitive data...");

  // Client will enable all other work
  const client = new Virtru.Client({ email });

  // Protect the sensitive data
  const encryptParams = new Virtru.EncryptParamsBuilder()
    .withStringSource(plainText)
    .build();
  const ciphertextStream = await client.encrypt(encryptParams);
  console.log(await ciphertextStream.toString());
}

// Set up Virtru auth widget
Virtru.AuthWidget("virtru-auth-widget-mount", { afterAuth });

4. Access the sensitive data now

Now, let’s say you need to see your sensitive data again immediately. Well, you’re still authenticated as [email protected] so you can decrypt the ciphertext:

async function afterAuth(email) {
  // Ask for sensitive data
  const plainText = prompt("Type something to encrypt: ", "sensitive data...");

  // Client will enable all other work
  const client = new Virtru.Client({ email });

  // Protect the sensitive data
  async function encryptToString(plain) {
    const encryptParams = new Virtru.EncryptParamsBuilder()
      .withStringSource(plain)
      .withDisplayFilename("sensitive.txt")
      .build();
    const ciphertextStream = await client.encrypt(encryptParams);
    const ciphertext = await ciphertextStream.toString();
    return ciphertext;
  }
  let ciphertext = await encryptToString(plainText);

  // Access the sensitive data now
  async function decryptFromString(ciphertext) {
    const decryptParams = new Virtru.DecryptParamsBuilder()
      .withStringSource(ciphertext)
      .build();
    const plaintextStream = await client.decrypt(decryptParams);
    const plaintext = await plaintextStream.toString();
    return plaintext;
  }
  let decrypted = await decryptFromString(ciphertext);

  // Validate that the original value and its decrypted version are the same.
  if (plainText === decrypted) {
    alert("The decrypted string matches your original one!");
  } else {
    alert(
      `ERROR: Output, [${decrypted}], does not match input, [${plainText}]`
    );
  }
}

// Set up Virtru auth widget
Virtru.AuthWidget("virtru-auth-widget-mount", { afterAuth });

But what if you close this tab or stop your web server? We need to remember the sensitive data we protected to access it later.

5. Access the sensitive data again later

The Virtru SDK lets you save your ciphertext as an HTML file you can open again later. This is also asynchronous.

async function afterAuth(email) {
  // Ask for sensitive data
  const plainText = prompt("Type something to encrypt: ", "sensitive data...");

  // Client will enable all other work
  const client = new Virtru.Client({ email });

  // Protect the sensitive data
  async function encryptToFile(text, encryptedFilename) {
    let displayFileName = encryptedFilename.replace(".tdf.html", "");
    const encryptParams = new Virtru.EncryptParamsBuilder()
      .withStringSource(text)
      .withDisplayFilename(displayFileName)
      .build();
    const ciphertextStream = await client.encrypt(encryptParams);
    await ciphertextStream.toFile(encryptedFilename);
  }

  // Access the sensitive data again later
  let encryptedFilename = "sensitive.txt.tdf.html";
  await encryptToFile(plainText, encryptedFilename);
}

// Set up Virtru auth widget
Virtru.AuthWidget("virtru-auth-widget-mount", { afterAuth });

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

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

Decrypting with Virtru Secure Reader

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

Updated 8 days ago


Quick Start: Client-side JavaScript


Suggested Edits are limited on API Reference Pages

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